 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| USER'S GUIDE ZSPTM SDK Software Development Kit April 2002 Revision 4.0 (R) This document contains proprietary information of LSI Logic Corporation. The information contained herein is not to be used by or disclosed to third parties without the express written permission of an officer of LSI Logic Corporation. DB15-000126-06, Third Edition (April 2002) This document describes Rev. 4.0 of LSI Logic Corporation's ZSPTM SDK Software Development Kit and will remain the official reference source for all revisions/releases of this product until rescinded by an update. LSI Logic Corporation reserves the right to make changes to any products herein at any time without notice. LSI Logic does not assume any responsibility or liability arising out of the application or use of any product described herein, except as expressly agreed to in writing by LSI Logic; nor does the purchase or use of a product from LSI Logic convey a license under any patent rights, copyrights, trademark rights, or any other of the intellectual property rights of LSI Logic or third parties. Copyright (c) 1999-2002 by LSI Logic Corporation. All rights reserved. TRADEMARK ACKNOWLEDGMENT The LSI Logic logo design and ZSP are trademarks or registered trademarks of LSI Logic Corporation. Microsoft, Microsoft Access, MS-DOS, Windows, and Windows NT are registered trademarks of Microsoft Corporation. UNIX is a registered trademark of X/Open Company, Ltd. Solaris is a trademark of Sun Microsystems, Inc. All other brand and product names may be trademarks of their respective companies. For a current list of our distributors, sales offices, and design resource centers, view our web page located at http://www.lsilogic.com/contacts/na_salesoffices.html ii Preface This book is the primary reference and user's guide for the ZSPTM SDK Software Development Kit. The SDK supports digital signal processors based on the ZSP400 core (for example, the LSI402ZX and LSI403Z) and the next generation ZSP G2 architecture. Audience This document assumes that you have some familiarity with the C language, and with the ZSP architecture and assembly language. Those who will benefit from this book are * * * Engineers and managers who are evaluating the ZSP processor for possible use in a system Engineers who are designing products based on the ZSP architecture and wish to perform cost and performance analysis Engineers who are developing software for systems based on the ZSP architecture Organization This document has the following chapters and appendices: * * * * * Chapter 1, Introduction, introduces the ZSP SDK software development kit. Chapter 2, Installation, describes how to install the SDK. Chapter 3, C Cross Compiler, describes the SDK C compiler. Chapter 4, Assembler, describes the assembler in the SDK tool set. Chapter 5, Linker, describes the linker in the SDK tool set. Preface iii * * * * * Chapter 6, Utilities, describes miscellaneous utilities in the SDK tool set. Chapter 7, ZISIM Simulator, describes the SDK functional-accurate simulator. Chapter 8, ZSIM Simulator, describes the SDK cycle-accurate simulator. Chapter 9, Debugger, describes the SDK debugger. Chapter 10, ZSP Integrated Development Environment (ZSP IDE), describes the SDK Project Manager provided by LSI Logic with Windows 95/98/NT versions of the SDK. Chapter 11, ZSP IDE Debugger, describes the GUI Debugger provided by LSI Logic with Windows 95/98/NT versions of the SDK. Appendix A, Example Programs, provides a sample program for use with the SDK. Appendix B, ZSP400 Control Registers, lists the ZSP400 control registers. Appendix C, ZSPG2 Control Registers, lists the ZSPG2 control registers. Appendix D, L-Intrinsic Functions, describes the L-Intrinsic functions supported by the SDK compiler. Appendix E, Signal Processing Library, describes the libalg.a library. * * * * * * Related Publications LSI402ZX Digital Signal Processor User's Guide, LSI Logic Corporation, order number R14021. Provides detailed information on the LSI402ZX Digital Signal Processor. LSI403Z Digital Signal Processor User's Guide, LSI Logic Corporation, order number R14025. Provides detailed information of the LSI403Z digital Signal Processor. ZSP400 Digital Signal Processor Architecture Technical Manual, LSI Logic Corporation, order number I14036. Provides detailed information on the registers and instruction set defined by the ZSP architecture and implemented in the LSI4xx family of processors. iv Preface Using and Porting GNU CC, by Richard M. Stallman, Free Software Foundation, June 1996. Provides detailed information on how to use GCC, which is the foundation of SDCC. Using AS: The GNU Assembler, by Dean Elsner, et. al., Free Software Foundation, January 1994. Provides detailed information on how to use AS, which is the foundation of SDAS. Using LD: The GNU Linker, by Steve Chamberlain, Free Software Foundation, January 1994. Provides detailed information on how to use LD, which is the foundation of SDLD. Debugging with GDB: The GNU Source Level Debugger, by Richard Stallman, et. al., Free Software Foundation, January 1994. Provides detailed information on how to use GDB, which is the foundation of SDBUG. EB402 Evaluation Board Getting Started, LSI Logic Corporation, order number DBO6-000264-01, September, 2000. Provides information on using the EB402 Evaluation Board. EB402 Evaluation Board User's Guide, LSI Logic Corporation, order number DB15-000143-00, September, 2000. Provides detailed information on how to use the EB402 Evaluation Board. PCMCIA-1149.1 Windows 95/NT Software Development Kit User's Guide, Corelis, Inc. Provides detailed information on using the JTAG interface. Man pages for ar, nm, objdump, string, size, objcopy, strip and ranlib from the Free Software Foundation, available from the FTP site prep.ai.mit.edu. Conventions Used in This Manual The first time a word or phrase is defined in this manual, it may be italicized. Hexadecimal numbers are indicated by the prefix "0x", for example, 0x32CF. Binary numbers are indicated by the prefix "0b", for example, 0b0011.0010.1100.1111. Preface v The term `DOS', unless otherwise noted, includes the MS-DOS operating system and its Windows 3.1, Windows 95, Windows 98, and Windows NT supersets. The term `PC', unless otherwise noted, includes the 386-, the 486-, and the Pentium-based IBM-PC or compatible host computers. Additional notational conventions used throughout this manual are listed below. Notation courier typeface bold typeface Example .nwk file fd1sp Meaning and Use Names of commands, files, directories, and code are shown in courier typeface In a command line, command keywords are shown in bold, nonitalic courier typeface. Enter them exactly as shown, including case. In command lines and syntax descriptions, italics indicate user-defined variables of a type defined by the italicized noun. Italicized text must be replaced with appropriate user-specified items. When an underscore appears in an italicized string, enter a user-supplied item of the type called for, without spaces. italics module italic underscore full_pathname brackets [ version ] In command formats, you may, but need not, enter an [ filename | register ] item enclosed within brackets. When vertical bars are used within brackets, you may select one (but not more than one) of the items separated by bars. Do not enter the brackets or bar. { directory } In command formats, you must select one (but not { filename | register } more than one) item enclosed within braces. Do not enter the braces. When vertical bars are used within braces, you may select one (but not more than one) of the items separated by braces. Do not enter the braces or bar. option... In command formats, elements preceding ellipses may be repeated any number of times. Do not enter the ellipses. In menu items, if an ellipsis appears after an item, clicking that item brings up a dialog box. braces ellipses vi Preface Notation vertical dots Example . . . ; Meaning and Use Vertical dots indicate that a portion of a program or listing has been omitted from the text. Use as shown in the text. semicolon, and other punctuation Preface vii viii Preface Contents Chapter 1 Introduction 1.1 1.2 Chapter 2 Installation 2.1 2.2 Contents of the CD-ROM Installation on Windows Systems 2.2.1 Installing SDK Tools 2.2.2 Restarting Windows Uninstalling the SDK Tools on Windows Systems Installation on Solaris Systems 2-1 2-1 2-2 2-9 2-9 2-10 Overview of the SDK Tools Overview of Software Development Using the SDK Tools 1-2 1-5 2.3 2.4 Chapter 3 C Cross Compiler 3.1 3.2 3.3 3.4 3.5 Compiler Options 3-2 Compiler Conventions 3-4 3.2.1 Data Type Conventions 3-5 3.2.2 Register Usage 3-6 3.2.3 Conventions Used for Passing Parameters 3-9 3.2.4 Run Time Stack 3-10 3.2.5 Example Code for Function Prologue and Epilogue 3-11 3.2.6 Parameter Passing Examples 3-13 Run Time Environment 3-15 C Run Time Library Functions 3-15 N-Intrinsics 3-16 3.5.1 Vector N-Intrinsics 3-18 3.5.2 ETSI Functions 3-18 Contents ix 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 Circular Buffers Accessing Control Registers Q15 Support Inline Assembly 3.9.1 Syntax 3.9.2 Parameterized Assembly 3.9.3 Variables and Expressions 3.9.4 Explicitly Clobbered Registers 3.9.5 Examples of asm Directive 3.9.6 Optimization of Inline Assembly Assembly Optimizer and Handwritten Assembly Debugging Options Code Statistics Example Compilations 3.13.1 Example 1 3.13.2 Example 2 3.13.3 Example 3 3.13.4 Example 4 3-20 3-21 3-22 3-23 3-23 3-23 3-24 3-25 3-25 3-28 3-28 3-29 3-29 3-30 3-30 3-30 3-30 3-30 Chapter 4 Assembler 4.1 Assembly Language Syntax 4.1.1 Assembler Options 4.1.2 Assembler Directives 4.1.3 Assembler Special Cases 4-1 4-2 4-3 4-4 Chapter 5 Linker 5.1 Sections 5.1.1 Symbols 5.1.2 Linker command file 5.1.3 Linker options 5-1 5-2 5-3 5-3 Chapter 6 Utilities 6.1 6.2 sdar sdstrip 6-2 6-5 x Contents 6.3 6.4 6.5 6.6 6.7 6.8 Chapter 7 ZISIM Simulator 7.1 sdranlib sdnm sdsize sdstrings sdobjdump sdobjcopy 6-7 6-8 6-9 6-11 6-12 6-14 7.2 Using ZISIM 7.1.1 Batch Mode 7.1.2 Interactive Mode ZISIM Commands 7.2.1 alias 7.2.2 clear break 7.2.3 clear dmem 7.2.4 clear imem 7.2.5 clear stats 7.2.6 disable break 7.2.7 disable trace 7.2.8 dump dmem 7.2.9 dump imem 7.2.10 enable break 7.2.11 enable trace 7.2.12 exit 7.2.13 fill dmem 7.2.14 fill imem 7.2.15 help 7.2.16 load dmem 7.2.17 load exe 7.2.18 load imem 7.2.19 reset 7.2.20 run 7.2.21 script 7.2.22 set attr 7.2.23 set break 7.2.24 set reg 7-1 7-1 7-2 7-4 7-7 7-8 7-8 7-8 7-9 7-9 7-9 7-9 7-10 7-11 7-11 7-11 7-12 7-12 7-12 7-13 7-13 7-14 7-14 7-15 7-15 7-16 7-17 7-17 Contents xi 7.3 7.4 Chapter 8 ZSIM Simulator 8.1 7.2.25 set size 7.2.26 show attr 7.2.27 show bits 7.2.28 show break 7.2.29 show dmem 7.2.30 show imem 7.2.31 show reg 7.2.32 show size 7.2.33 show stats 7.2.34 show trace 7.2.35 step 7.2.36 unalias I/O Port Usage Example Session Using ZISIM 7-17 7-18 7-19 7-19 7-20 7-20 7-21 7-22 7-22 7-23 7-23 7-23 7-24 7-24 8.2 Using ZSIM 8.1.1 Batch Mode 8.1.2 Interactive Mode ZSIM Commands 8.2.1 alias 8.2.2 clear break 8.2.3 clear dcache 8.2.4 clear dmem 8.2.5 clear icache 8.2.6 clear imem 8.2.7 clear stats 8.2.8 disable break 8.2.9 disable profile 8.2.10 disable trace 8.2.11 dump dmem 8.2.12 dump imem 8.2.13 enable break 8.2.14 enable profile 8.2.15 enable trace 8.2.16 exit 8-1 8-1 8-2 8-5 8-11 8-11 8-11 8-12 8-12 8-12 8-13 8-13 8-13 8-14 8-14 8-14 8-15 8-15 8-16 8-17 xii Contents 8.3 8.4 8.2.17 fill dmem 8.2.18 fill imem 8.2.19 help 8.2.20 istep 8.2.21 load dmem 8.2.22 load exe 8.2.23 load imem 8.2.24 reset 8.2.25 run 8.2.26 script 8.2.27 set attr 8.2.28 set break 8.2.29 set delay 8.2.30 set latency 8.2.31 set reg 8.2.32 set size 8.2.33 show attr 8.2.34 show bits 8.2.35 show break 8.2.36 show dcache 8.2.37 show dmem 8.2.38 show icache 8.2.39 show imem 8.2.40 show pipe 8.2.41 show profile 8.2.42 show reg 8.2.43 show rule 8.2.44 show size 8.2.45 show stats 8.2.46 show trace 8.2.47 step 8.2.48 unalias I/O Port Usage Example Session Using ZSIM 8-17 8-17 8-18 8-18 8-19 8-19 8-20 8-20 8-21 8-21 8-22 8-23 8-23 8-24 8-24 8-24 8-25 8-26 8-26 8-26 8-28 8-28 8-29 8-29 8-30 8-30 8-31 8-31 8-32 8-32 8-32 8-33 8-33 8-34 Contents xiii Chapter 9 Debugger 9.1 9.2 Using SDBUG SDBUG Execution Environments 9.2.1 Functional-Accurate Simulator Connection 9.2.2 Cycle-Accurate Simulator Connection 9.2.3 UART Connection 9.2.4 JTAG Controller Connection Debugger Commands - Special Cases 9.3.1 Generic Target-Specific Commands 9.3.2 Backtrace Command 9.3.3 Info Registers Command 9.3.4 Breakpoint Command 9.3.5 Print Command 9.3.6 Set Command 9.3.7 Cycle-Step Command 9.3.8 Accessing Memory with the Debugger Dynamic Breakpoints Example Debugging Sessions 9.5.1 Example 1 9.5.2 Example 2 9-1 9-3 9-3 9-4 9-7 9-8 9-11 9-11 9-11 9-12 9-12 9-12 9-12 9-13 9-13 9-15 9-15 9-16 9-19 9.3 9.4 9.5 Chapter 10 ZSP Integrated Development Environment (ZSP IDE) 10.1 ZSP IDE Overview 10.1.1 Introduction to Workspaces and Projects 10.2 Working With Workspaces and Projects 10.2.1 Working With Workspaces 10.2.2 Working With Projects 10.3 Project Settings 10.3.1 Build methodology and Project Tree Structure 10.3.2 Compiler/Assembler Settings 10.3.3 Linker Settings 10.4 ZSP IDE Detailed Description 10.4.1 Paned Window Controls 10.4.2 Project Tree 10.4.3 Main Menu 10-2 10-2 10-4 10-4 10-7 10-9 10-10 10-10 10-14 10-17 10-17 10-17 10-19 xiv Contents 10.4.4 Toolbar 10.5 Shell Window 10.6 Disassembly Window 10.7 Parallel Debug Manager 10.8 Help Menu 10.9 Editor 10.10 ZSP IDE File Formats Chapter 11 ZSP IDE Debugger 11.1 GUI Debugger Overview 11.1.1 Main Window 11.1.2 Title Bar - Project File Name Display 11.1.3 Window Area 11.1.4 Status Area 11.1.5 Main Menu 11.1.6 Main Toolbars 11.1.7 Debugging Windows (General) Detailed Descriptions 11.2.1 Main Menu 11.2.2 Debugging Window Detailed Descriptions 10-29 10-32 10-33 10-33 10-34 10-34 10-35 11.2 11-3 11-3 11-3 11-3 11-3 11-3 11-4 11-6 11-11 11-11 11-19 Appendix A Example Programs A.1 A.2 Example Program: demo.c Example Program hw_dbg.s A-1 A-5 Appendix B ZSP400 Control Registers Appendix C ZSPG2 Control Registers Appendix D L-Intrinsic Functions Contents xv Appendix E Signal Processing Library E.1 API Specification Auto-correlation Library Function on G2 E-2 E.1.1 Auto-correlation E-2 E.2 API Specification for Convolutional Encoder Library Function on G2 E-3 E.2.1 Convolutional Encoder E-3 E.3 API Specification for 16bit CRC Library Function on G2 E-5 E.3.1 CRC 16bit E-5 E.4 API Specification for 8bit CRC Library Function on G2 E-6 E.4.1 CRC 8bit E-6 E.5 API Specification for 32 bit Division Library Function on G2 E-7 E.5.1 32 bit Division E-7 E.6 API Specification for IIR Library Function on G2 E-8 E.6.1 IIR E-8 E.7 API Specification for IIR Biquad Library Function on G2 E-9 E.7.1 IIR Biquad E-9 E.8 API Specification for Inverse Square Root Library Function on G2 E-10 E.8.1 Inverse Square Root E-10 E.9 API Specification for Synthesis Lattice Filter Library Function on G2 E-11 E.9.1 Synthesis Lattice Filter E-11 E.10 API Specification for Real Block FIR Library Function on G2 E-12 E.10.1 Real Block FIR E-12 E.11 API Specification for 256 point FFT Library Function on G2 E-14 E.11.1 256 point FFT E-14 Index Customer Feedback xvi Contents Figures 1.1 9.1 9.2 10.1 10.2 10.3 10.4 10.5 10.6 10.7 10.8 10.9 10.10 10.11 10.12 10.13 10.14 10.15 10.16 10.17 10.18 10.19 10.20 10.21 10.22 10.23 10.24 10.25 10.26 10.27 10.28 11.1 11.2 11.3 11.4 11.5 Overview of Software Development Debugger Memory Addressing (sdbug400, zdxbug) Debugger Memory Addressing (zdbug) ZSP IDE Tools Suite Implementation ZSP IDE Workspace ZSP IDE Main Window Recent Workspaces List File Selection Dialog Project Menu Compiler Settings Assembler Settings Paned Window Handles ZSP IDE Project Tree ZSP IDE File Menu ZSP IDE Edit Menu ZSP IDE View Menu Customize Toolbar ZSP IDE Project Menu ZSP IDE Workspace Menu ZSP IDE Build Menu Build / Compile Output Window Build Output Window Popup Menu ZSP IDE Debug Menu Debug Settings Debug Window Settings Object File Utility Utility Output Window Showing Disassembled Code Shell Window Disassembly Window Parallel Debug Manager Setup Window Parallel Debug Manager Control Window Menu Checkmarks For Debugging Windows Tools Menu - Invoke Toolbars Preferences - Use Images For Toolbar Buttons Toolbar Buttons With Text Annotation Toolbar Buttons With Image Annotation 1-6 9-14 9-15 10-2 10-2 10-3 10-5 10-5 10-8 10-12 10-12 10-17 10-17 10-20 10-21 10-21 10-23 10-23 10-24 10-24 10-25 10-25 10-26 10-27 10-27 10-29 10-29 10-32 10-33 10-33 10-34 11-4 11-5 11-5 11-6 11-6 xvii 11.6 11.7 11.8 11.9 11.10 11.11 11.12 11.13 11.14 11.15 11.16 11.17 11.18 11.19 11.20 11.21 11.22 11.23 11.24 11.25 11.26 11.27 11.28 11.29 11.30 11.31 11.32 11.33 11.34 11.35 11.36 11.37 11.38 11.39 11.40 11.41 11.42 11.43 Debugger Paned Window 11-7 Paned Window Handles 11-8 Preferences - Set Main Window Columns 11-8 Top Level Debugging Window 11-9 Top Level Window Focus Control 11-9 Preferences - Separate New Window 11-9 Display Controls for Paned Window 11-10 Display Controls for Top Level Window 11-10 Preferences - Autoload Windows 11-10 Breakpoint Menu 11-12 Source Code Window Current Selection Line 11-12 Source Code Window Breakpoints 11-13 Execute Menu 11-15 Program View Menu 11-18 Target View Menu 11-18 Tools Menu 11-19 Source Code Window 11-20 Progress Bar Window 11-21 Source Code Window (shown with Disassembly Window) 11-21 Example Source Code Popup Query Result 11-22 Breakpoint List Window 11-23 Debugging Symbols Window 11-24 Call Stack Window 11-24 Local Variables Window 11-25 Global Variables Window 11-25 .Expression Window 11-26 Watch Expressions Window 11-26 ZSIM Profile Window 11-27 ZSIM Statistics Window 11-27 Disassembly Window 11-28 Register Element Popup Format Menu 11-29 Register Window Format Menu 11-29 Register Window Columns Menu 11-30 Register Window Configure Menu 11-30 Control Register Window - Standard Mode 11-30 Control Register Bitfield Entry Annotation 11-31 Control Register Window - Bitfield Mode 11-31 Operand Register Window 11-32 xviii 11.44 11.45 11.46 11.47 11.48 11.49 11.50 11.51 Address Register Window Memory Window ZSIM Grouping Rule Window ZSIM Pipeline Window Command Line Window Preferences Window - Logging Tools Menu - Session Log File Session Log Window 11-32 11-32 11-33 11-33 11-34 11-34 11-35 11-35 xix xx Tables 1.1 1.2 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 8.1 8.2 8.3 8.4 8.5 SDK Tools and GNU Counterparts SDK Utilities and GNU Counterparts Compiler Options Output Options Optimization Options Compiler's Representation of C Data Types Effect of Mode Bits on Compiler-Generated Code Stack Frame Layout Stack Frame Example N-Intrinsic Functions Vector N-Intrinsics ETSI to N-Intrinsic Mapping Parameter Output Syntax Argument Constraints SDK Utilities and GNU Counterparts sdar p Keyletter Options sdar p Keyletter Modifiers sdstrip Options sdnm Options sdsize Options sdstrings Options sdobjdump Options sdobjcopy Options ZISIM Command-line Options ZISIM Command Summary ZISIM400 specific commands ZISIMG2 specific commands Configurable ZISIM Attributes Default Arguments for show dmem Default Arguments for show imem I/O Device Memory Map and Associated Files ZSIM Command-line Options Command-line Options for zsim400 Command-line Options for zsimg2 ZSIM Command Summary ZSIM400 specific commands 1-3 1-4 3-2 3-4 3-4 3-5 3-8 3-10 3-11 3-17 3-18 3-19 3-23 3-24 6-1 6-3 6-4 6-6 6-8 6-9 6-11 6-13 6-15 7-3 7-4 7-6 7-7 7-16 7-20 7-20 7-24 8-3 8-4 8-5 8-5 8-9 xxi 8.6 8.7 8.8 8.9 8.10 9.1 9.2 9.3 9.4 9.5 9.6 9.7 10.1 10.2 10.3 10.4 11.1 11.2 11.3 B.1 C.1 D.1 ZSIMG2 specific commands Configurable ZSIM Attributes Default Arguments for show dmem Default Arguments for show imem I/O Device Memory Map and Associated Files Debugger Names SDBUG-Only Options SDBUG Target ZISIM Simulator Commands SDBUG Target ZSIM Commands SDBUG UART Connection Commands SDBUG JTAG Commands Hardware-Assisted Debugging Commands Compiler/Assembler Options Linker options ZSP IDE Toolbar Command Line Debugger Executables Debugger Targets Keyboard Shortcuts ZSP400 Control Registers G2 Control Registers Long Intrinsic Functions 8-10 8-22 8-28 8-29 8-33 9-2 9-2 9-4 9-5 9-8 9-9 9-10 10-13 10-16 10-30 10-35 11-2 11-2 11-16 B-1 C-1 D-1 xxii Chapter 1 Introduction The ZSP Software Development Kit (ZSP SDK) from LSI Logic supports all aspects of software development for systems incorporating devices based on the ZSP400 and ZSPG2 architectures. The ZSP SDK includes an optimizing C cross compiler, assembler, and linker, both a functionalaccurate simulator and a cycle-accurate simulator, and a source- and assembly-level debugger. The ZSP SDK is available for Windows 95, Windows 98, Windows NT, and Solaris platforms. For the Windows platforms only, the software development tools can be used in the context of the SDK Integrated Development Environment (IDE), which includes a project manager and a GUI debugger. The GUI debugger provides a graphical environment for developing and debugging your code, with interactive viewing and control of project source files and run-time data. ZSP SDK Software Development Kit 1-1 1.1 Overview of the SDK Tools The ZSP SDK tools are all placed under one directory which is referred to with the environment variable SDSP_HOME. The sdspI subdirectory contains all tools related to the ZSP400 architecture. The ZSPg2 subdirectory contains all tools related to the ZSPG2 architecture. There are no dependencies between the two directories. Users who only need tools for the ZSP400 can delete the ZSPg2 subdirectory. Likewise, users who only need tools for the ZSPG2 can delete the sdspI subdirectory. The two subdirectories closely mirror one another. Both have the following subdirectories: bin, lib, include, misc, tmp. The bin directories contain the command-line tools. The lib directories contain the C libraries. The include directories contain the C header files. The misc directories contain auxilary files. The tmp directories are used by the tools for temporary space. The GNU based tools for the ZSP400 all have a "sd" prefix. The analgous tools for ZSPG2 all have a "zd" prefix. In addition the assembly optimizer, sdopt/zdopt, also follows this prefix convention. The simulators do not follow this convention. The ZSP400 simulators are: zsim400 and zisim400. The ZSPG2 simulators are: zsimg2 and zisimg2. The ZSP SDK also supports users who want to take assembly and C code written for the ZSP400 architecture and run it without modification on the ZSPG2 architecture. The compiler zdxcc compiles for a ZSPG2 target but uses the calling convention and pointer sizes designed for the ZSP400. The ZSPg2 directory also contains a subdirectory libg1g2, which contains C libraries for zdxcc. There is also a debugger, zdxbug, for debugging code developed with zdxcc. The ZSP SDK tools are based on the GNU tools from the Free Software Foundation, Inc. The GNU project has well-proven software development tools that have been successfully ported to many different target machines and platforms. Documentation for the GNU project tools can be obtained from the web site www.gnu.org and the FTP site prep.ai.mit.edu. To gain access to the FTP site, log in as `anonymous' and type your e-mail address as the password. The descriptions of the tools in this document, for the most part, include only the differences from their GNU counterparts (refer to Table 1.1). 1-2 Introduction Table 1.1 SDK Tools and GNU Counterparts GNU Equivalent gcc Tool sdcc zdcc zdxcc sdas zdas sdld zdld sdbug400 zdbug zdxbug Function Compiles as ld gdb Assembles Links Debugs The GNU tools have been enhanced so as to take advantage of the many high-performance features of the ZSP LSI402ZX and LSI403Z devices and ZSP400-based ASICs, such as single-cycle multiplyaccumulate instructions, fast context switching, circular buffer support, single-cycle compare/select, and zero-overhead loops. The SDK provides utilities for manipulating the files that are generated by the tools during project creation. These SDK-specific utilities, described in Table 1.2, replace their GNU counterparts. Overview of the SDK Tools 1-3 Table 1.2 SDK Utilities and GNU Counterparts GNU Equivalent ar nm objdump ranlib strings size strip objcopy Utility sdar zdar sdnm zdnm sdobjdump zdobjdump sdranlib zdranlib sdstrings zdstrings sdsize zdsize sdstrip zdstrip sdobjcopy zdobjcopy Function Creates, modifies, and extracts files from an archive. Lists symbols from object files. Displays information from object files. Generates an index for an archive. Prints the printable characters in the files. Lists section sizes and total size of object file. Discards symbols from object files. Copies and translates object files. The SDK Tools also includes the following non-GNU-based tools: * * The compiler's optimizer, sdopt/zdopt/zdxopt, performs additional optimizations to those performed by SDCC/ZDCC/ZDXCC. Both the functional-accurate and cycle-accurate simulators are provided in a standalone form that support a simple command-line interface and that can be provided in a dynamic linkable format that can be used in conjuction with the debugger. For Windows platforms only, the GUI tools include an IDE and a GUI Debugger. * For Solaris platforms, there are freely-available GUI front ends that do not have all the capabilities of the GUI supplied by LSI Logic for Windows platforms, but that can be configured for use with all the LSI Logic ZSP SDK Tools. 1-4 Introduction 1.2 Overview of Software Development Using the SDK Tools An overview of the software development process utilizing the SDK tools is shown in Figure 1.1. As shown in the figure, the compiler accepts C source files (.c ) and produces a relocatable assembly language source module (.s). The assembly source file is input to the assembler, which translates the module into a relocatable object file in the Executable and Linkable Format (ELF) file format (.obj (Windows) or .o (UNIX)). ELF files are then linked with other ELF files (for example, library files) to produce a single executable ELF load file (a.out). The load file can be loaded into host memory for symbolic simulation/debugging, or it can be downloaded to a ZSP architecture-based target system for real-time debugging. On Windows 95/98/NT and Solaris platforms, the tools can be accessed using the standard GNU command-line interface, as described in Chapter 3, "C Cross Compiler" through Chapter 9, "Debugger." On Windows 95/98/NT platforms, the tools can also be accessed using the the ZSP Integrated Development Environment (ZSP IDE), (Chapter 10, "ZSP Integrated Development Environment (ZSP IDE)"), and the ZSP IDE Debugger (Chapter 11, "ZSP IDE Debugger"). Overview of Software Development Using the SDK Tools 1-5 Figure 1.1 Overview of Software Development C Source Files C Compiler Assembler Source Files Optimizer Assembler Source Files Macropreprocessor Assembler Listing File Archiver ELF Object File Libraries Linker ELF Load File Debugger Simulator 1-6 Introduction Chapter 2 Installation This chapter describes how to install the ZSP Software Development Kit. The SDK is available for Windows 95, Windows 98, Windows NT, and Solaris. The media used to provide the tools is a CD-ROM. 2.1 Contents of the CD-ROM The CD-ROM has the following five top-level directories: * doc Contains the complete documentation for the SDK tools and the GNU tools. * * examples Contains example code for the SDK tools. solaris Contains initialization code and tools for installing the SDK on the Solaris platform. * windows Contains the initialization code and tools for installing the SDK on Windows 95/98/NT platforms, and examples that can be added to an ZSPIDE project. 2.2 Installation on Windows Systems The minimum system requirements for the SDK tools are * a Pentium Pro-based PC ZSP SDK Software Development Kit 2-1 * * 64 Mbytes of RAM 48 Mbytes of Disk Space On Windows NT systems, you must have administrator privileges to install the ZSP SDK Tools. 2.2.1 Installing SDK Tools Before you install the SDK tools, make sure you have uninstalled any older version. Refer to Section 2.3, "Uninstalling the SDK Tools on Windows Systems." Step 1. Insert the CD-ROM in the CD drive, click Add/Remove Program on the Control Panel, then click Install and select D:\windows\Setup.exe. Step 2. Follow the Setup Instructions. Step 3. A dialog box will be displayed for entering the serial Number. Step 4. Type the serial Number, and then click on the Next button. The dialog box shown below will be displayed. 2-2 Installation Step 5. The default directory is C:\Program Files\SDK Tools . Filename elfread.exe libzisim400.dll1 libzsim400.dll1 libzperiph.dll1 Function Produces a simple dump of entire contents of an object file Dynamic link library used in sdbug400 for target zisim Dynamic link library used in sdbug400 for target zsim Dynamic link library used in sdbug400 for target zsim (Sheet 1 of 2) Installation on Windows Systems 2-3 Filename sdar.exe sdas.exe sdbug400.exe sdcc.exe sdcc1.exe1 sdcpp.exe1 sdld.exe sdnm.exe sdobjcopy.exe sdobjdump.exe sdopt.exe1 sdranlib.exe sdsize.exe sdstrings.exe sdstrip.exe zisim400.exe zsim400.exe Function Archive utility Assembler Source-level debugger for ZSP400-based Devices Driver Compiler Preprocessor Linker Symbol listing utility Object file copying utility Object dump utility Optimizer Ranlib utility Size utility String print utility Symbol discarding utility Functional-accurate simulator for ZSP400-based devices Cycle-accurate simulator for ZSP400-based devices (Sheet 2 of 2) 1. These files are not intended to be used on the command line, but instead are always called by other functions. 2-4 Installation The libraries listed below are installed by default in the directory C:Installation_Directory\sdspI\lib. Filename crt0.obj libc.a libg.a liblongc.a Function Startup file C library C library with debug information C library with long calls. The header files listed below are installed by default in the directory C:\Installation_Directory\sdspI\include. Filename cbuf.h ctype.h creg.h dsp.h libsdsp.h limits.h N_Intrinsic.h q15.h setjmp.h simios.h stdarg.h stddef.h stdio.h stdlib.h string.h Function Circular buffer Standard header file Control registers L-Intrinsics SDSP-specific printing Standard header file N-Intrinsics Support file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file Installation on Windows Systems 2-5 By default, the Setup program installs the files listed below in C:\Installation_Directory\ZSPg2\bin, where Installation_Directory is the directory specified in Step 5 . Filename elfread.exe libzisimg2.dll1 libzidlmssg2.dll1 zdar.exe zdas.exe zdbug.exe zdxbug.exe zdcc.exe zdxcc.exe zdcc1.exe1 zdxcc1.exe1 zdcpp.exe1 zdxcpp.exe1 zdld.exe zdnm.exe zdobjcopy.exe zdobjdump.exe zdopt.exe1 zdxopt.exe1 zdranlib.exe (Sheet 1 of 2) Function Produces a simple dump of entire contents of an object file Dynamic link library used in zdbug and zdxbug for target zisim Dynamic link library used in zdbug and zdxbug for target zisim Archive utility Assembler Source-level debugger for ZSP500-based Devices Source-level debugger for ZSP500-based devices running code designed for ZSP400 Compiler Cross ("X") compiler for ZSP400 to ZSP500 Compiler Driver for zdcc Compiler Driver for zdxcc Preprocessor Preprocessor for zdxcc Linker Symbol listing utility Object file copying utility Object dump utility Optimizer Optimizer for ZSP400 to ZSP500 code. Ranlib utility 2-6 Installation Filename zdsize.exe zdstrings.exe zdstrip.exe zisimg2.exe Function Size utility String print utility Symbol discarding utility Functional-accurate simulator for ZSP400-based devices (Sheet 2 of 2) The libraries listed below are installed by default in the directory C:Installation_Directory\ZSPg2\lib. Filename crt0.obj libc.a libg.a Function Startup file C library C library with debug information The libraries listed below are installed by default in the directory C:Installation_Directory\ZSPg2\lib.g1g2 Filename crt0.obj libc.a libg.a libalg.a Function Startup file C library C library with debug information Basic signal processing functionality Installation on Windows Systems 2-7 The header files listed below are installed by default in the directory C:\Installation_Directory\ZSPg2\include. Filename cbuf.h ctype.h creg.h dsp.h libsdsp.h limits.h N_Intrinsic.h q15.h setjmp.h simios.h stdarg.h stddef.h stdio.h stdlib.h string.h Function Circular buffer Standard header file Control registers L-Intrinsics SDSP-specific printing Standard header file N-Intrinsics Support file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file The files listed below are installed by default in the directory C:Installation_Directory\ide\bin Filename en.rc guidebug.exe ZSPide.exe Function IDE menu resource GUI debugger frontend. IDE for the ZSP family of processors. 2-8 Installation 2.2.2 Restarting Windows The Setup program installs system files and updates some shared files that are required for running the SDK tools. The system prompts you to reboot after you have installed the SDK tools. Click Finish to exit from the Setup program.The system will be restarted according to the option selected in the above dialog box. 2.3 Uninstalling the SDK Tools on Windows Systems Perform the following steps to uninstall the SDK tools: Step 1. Open the Control Panel window. (The Control Panel is accessed by clicking on the Start menu, then selecting Settings, then selecting Control Panel. Step 2. In the Control Panel window, double-click on Add/Remove Program. Step 3. Then select the LSI LOGIC SDK tools and click on Add/Remove. In the dialog box shown below, click on Remove to uninstall the tools. Uninstalling the SDK Tools on Windows Systems 2-9 2.4 Installation on Solaris Systems The ZSP SDK may be hosted on the Solaris 2.6 operating system and later versions. Step 1. If your Solaris system has vold, it will automatically mount the CD-ROM after it has been inserted. To access the CD-ROM, change the directory to /cdrom/SDK. Step 2. If vold is not running, mount the CD-ROM and enter the following command: mount /dev/sr0 /mnt/cdrom Step 3. Use one of the following commands to invoke the installation script under /cdrom/SDK/solaris or /mnt/cdrom/solaris: /cdrom/SDK/solaris/sdsp_install or /mnt/cdrom/solaris/sdsp_install Step 4. Follow the directions given in the script. 2-10 Installation Step 5. Specify an installation directory for the SDK tools. Assign the installation path to the SDSP_HOME environment variable, followed by a forward slash (/). For example, if you install the tools in MyInstallDirectory, assign the directory to the SDSP_HOME variable: SDSP_HOME = MyInstallDirectory/ Step 6. Export the SDSP_HOME variable. Step 7. If you want to be able to invoke the SDK tools from any directory, add the installation directory to the path. Step 8. In order to use the sdbug400 debugger, the environment variable LD_LIBRARY_PATH must be included in the installation path. Use the following command: setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$SDSP_HOME/sdspI/bin The Setup program installs the SDK files. The following files containing the tools are installed in the directory $SDSP_HOME/sdspI/bin. Filename elfread sdar sdas sdbug400 sdcc sdcc1 sdcpp sdld sdnm sdobjcopy Function Produces a simple dump of entire contents of an object file Archive utility Assembler Source-level Debugger for ZSP400 Driver Compiler Preprocessor Linker Symbol listing utility Object file copying utility Installation on Solaris Systems 2-11 Filename sdobjdump sdopt sdranlib sdsize sdstrings sdstrip zisim400 zsim400 Function Object dump utility Optimizer Random library (ranlib) utility Size utility String print utility Symbol discarding utility Functional-accurate simulator for ZSP400-based Devices Cycle-accurate simulator for ZSP400-based Devices The libraries listed below are installed in the directory $SDSP_HOME/sdspI/lib. Filename crt0.o libc.a libg.a Function Startup file C library C library with debug information The header files listed below are installed in the directory $SDSP_HOME/sdspI/include. Filename cbuf.h ctype.h dsp.h libsdsp.h limits.h Function Circular buffer Standard header file L-Intrinsics SDSP-specific printing Standard header file 2-12 Installation Filename N_Intrinsic.h q15.h setjmp.h simios.h stdarg.h stddef.h stdio.h stdlib.h string.h Function N-Intrinsics Support file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file Standard header file For both the Windows and Solaris setups, there are additional files and directories installed by the Setup program that are required for running the tools. For this reason, do not delete or modify any of the files or directories in the installation directory. The ZSP SDK tools use the tmp directory, which is created during setup, to store temporary files. The misc directory contains a file called mapfile. This file contains information about the scan chain of the target processor that is used for hardware-assisted debug with the JTAG port (on Windows platforms only). The correct map file is required for hardware-assisted debugging. The map file supplied with the ZSP SDK tools corresponds to the LSI402ZX rev2. If you are using a different ZSP400-based part, you must replace the map file installed during setup with the proper map file for your device. Installation on Solaris Systems 2-13 2-14 Installation Chapter 3 C Cross Compiler This chapter describes the SDK C Cross Compiler and the compilation process. The SDK C Cross Compilers; SDCC, ZDCC, and ZDXCC; are based on the GNU C compiler (GCC) from the Free Software Foundation. SDCC is the compiler for the ZSP400 architecture. ZDCC is the compiler for the ZSPG2 architecture. ZDXCC is targeted for the ZSPG2 architecture, but it uses the same calling convention and pointer size as SDCC. This allows C/assembly programs written for the ZSP400 architecture to be easily ported to the ZSPG2 architecture. CC will be used to refer to all three compilers. GCC is described in Using and Porting GNU CC, by Richard M. Stallman, Free Software Foundation, June 1996. The description of CC in this chapter, for the most part, includes only the differences from GCC. The compiler is invoked from the shell using the following command: cc [options] sourcefile The command-line options and source file name extension determine the type of compilation. In the simplest case, with no options and a .c source file, the compiler will produce an executable, a.out. ZSP SDK Software Development Kit 3-1 3.1 Compiler Options The CC compiler supports all GCC compiler options in addition to the SDK-specific options described in Table 3.1. Table 3.1 Option -mlong_call Compiler Options Description The compiler generates code for a call instruction using a register operand. Use this option to resolve the limitation of the call immediate range. The compiler disables the assembly optimizer, sdopt/zdopt/zdxopt. By default, the optimizer is automatically invoked at optimization levels -O1, -O2 and -O3. The compiler generates code for a conditional branch by using a register operand. The compiler generates code for an unconditional branch by using a register operand. Enable the compiler to generate mac and macn instructions without using intrinsics. Use this option only if the code generated will be run with the sat, q15, sre and mre bits of %fmode turned off. Use large data model. Availability SDCC ZDCC ZDXCC1 SDCC ZDCC ZDXCC SDCC ZDXCC SDCC ZDXCC SDCC ZDXCC -mno_sdopt -mlong_cond_branch2 -mlong_uncond_branch3 -minfer_mac -mlarge_data ZDCC 1. Since the range of a call immediate on ZSPG2 is 16-bits versus 13-bits on ZSP400, the -mlong_call option will be less frequently needed for ZDXCC and ZDCC. 2. This option is preserved for backward compatibility with previous versions of the SDK, but it is no longer needed, since the compiler will automatically use register based branches when needed. This option will be removed in a future version of the SDK. 3. (same as 2.) The -mlong_call option is frequently necessary with SDCC because call-immediates on the ZSP400 architecture have a 13-bit range, and its use is therefore recommended for applications that are larger than the range of a call-immediate. The ZSPG2 architecture has a larger call immediate range (16-bits), so this option is not as critical for it. Better performance and code size can be obtained by selectively using the mlong_call option, but this may require repetitive trial and error to determine which files can safely be converted to use call-immediates. One important exception is a file which does not call a function external 3-2 C Cross Compiler to the file; in this case, the necessity of -mlong_call does not depend on other files or on the link order--this kind of file will either always require -mlong_call or it will never require it. Note that with SDCC, the use of -mlong_call does not guarantee that all calls will be long calls; that is, the assembly optimizer, sdopt, will convert long calls to call immediates if it can determine that such a conversion is safe. The assembly optimizer can be disabled by specifying the -mno_sdopt option; otherwise, it is automatically invoked when optimization is selected. Note that to debug optimized code, the -mno_sdopt option should be used, because the assembly optimizers perform optimizations that make debugging extremely difficult. sdopt takes in assembly generated by the compiler proper and optimizes it to produce improved assembly. The optimizations that sdopt performs include simplification of constant generation, conversion of loops to use loop registers, dead code elimination, loop invariant code motion, conversion of long calls to call-immediate, instruction scheduling, and improved register utilization. zdopt takes in assembly generated by ZDCC and optimizes it to produce improved assembly. The optimizations that zdopt performs include dead code elimination, loop invariant code motion, instruction scheduling, and improved register utilization. ZDCC supports two models of memory. The default small memory model requires that data and bss sections be placed in the first 64K words of data memory. The large data model has no requirements on the size or placement of the data and bss sections. The large data model is selected with the "-mlarge_data" option. For both models, the pointer size is 32bits. Both models allow stack and heap space to use all addressable memory. Code generated with the small data model will be more compact and have better performance than code generated with the large data model. The small data model allows a shorter instruction sequence to be used to access memory in the data or bss sections. Compiler Options 3-3 Some of the key options that control the compiler's output are shown in Table 3.2. Table 3.2 -c -o file -E -S -save-temps Output Options Compile or assemble source files but do not link. Output file is named by replacing the suffix of the source file with `.o'. Place output in file. This option is applicable whether the output is preprocessed C, assembly, an object file, or an executable. Stop after preprocessing. Output is sent to standard output. Stop after compilation. Do not assemble. Output file is named by replacing the `.c' suffix with `.s'. Store the intermediate preprocessed C, assembly, and object files permanently. The names used for these intermediate files will be based on the name of the input file: compiling foo.c with -save-temps will produce foo.i, foo.s, and foo.o. Generate debugging information for use by the debugger. -g The optimization levels supported by GCC are described in Table 3.3. Table 3.3 Option -O0 -O1 -O2 Optimization Options Description No optimization is performed. All variables are placed on the stack. Only those optimizations that allow the debugger to behave as expected are performed. Only those optimizations that do not greatly increase code size are performed. These optimizations include dead-code elimination, constant propagation, common subexpression elimination, and loop invariant code motion. All optimizations performed at level -O2 are performed, as well as function inlining and loop unrolling. -O3 3.2 Compiler Conventions This section describes the software conventions defined by the SDK assembler and compiler. You must follow these conventions when writing assembly-language routines that will be called by your C program. 3-4 C Cross Compiler 3.2.1 Data Type Conventions The compiler's representation of C data types is summarized in Table 3.4. The q15 data type can be printed by the fprintf and printf functions. The %q format specifier will print a 16-bit value in fixed-point notation. For example, the call: printf("%q\n",0x6000); will print: 0.75000 Table 3.4 C Data Type char unsigned char int short int unsigned short int q15 enum pointer long unsigned long accum_a accum_b Compiler's Representation of C Data Types Representation 16 bits 16 bits 16 bits 16 bits 16 bits 16 bits 16 bits 16 bits with SDCC/ZDXCC 32 bits with ZDCC 32 bits 32 bits 32 bits 32 bits Use the accum_a and accum_b data types to select a specific register for variable storage: variables declared as type accum_a or accum_b are placed in registers r1r0 and r3r2 respectively with SDCC/ZDXCC. They are placed in r13r12 and r15r14 respectively with ZDCC. This change was necessary with ZDCC because registers r0-r3 are clobbered by the ZSPG2 calling convention. The accum_a and accum_b data types can be Compiler Conventions 3-5 used to declare local variables; global accumulators are not supported. From the compiler's point of view, accum_a and accum_b are 32-bit variables that must be stored in a specified register. On the ZSP400, the accum_a and accum_b data types are placed in r1r0 and r3r2, respectively, to allow the use of accumulator-specific operations. Although the compiler treats accum_a and accum_b as 32-bit variables, the accumulator instructions (for example, mac.a, mac2.a, macn.a ... ) operate on a 40-bit accumulator. The high-order 8 bits for each accumulator are in the %guard register. If 40-bit accumulators are needed, the high-order bits can be accessed through inline assembly instructions that read or modify the %guard register. In ZSPG2, since every GPR pair supports accumulator operations, other accumulators can be used by declaring them with: register long acc_c asm("rX"); In fact, accum_a and accum_b declarations are equivalent to: register long x asm ("rX"); where "X" is the appropriate register. It should be remembered that only accumulators r12-r15 have their guard bits preserved across calls. 3.2.2 Register Usage 3.2.2.1 SDCC/ZDXCC Register Usage Register usage SDCC/ZDXCC is summarized below. Registers r0 through r15 are general-purpose registers, and registers beginning with `%' are control registers. * Registers used by the compiler: r0-r15, %fmode, %smode, %amode, %hwflag, %loop0, %loop1, %loop2, %loop3, %rpc, %pc, %cb0_beg, %cb0_end, %cb1_beg, %cb1_end, %guard. Stack pointer: r12 Parameter registers: r4-r6 Callee preserved registers: r0-r3, r7-r12, r14, r15, %guard There are no caller saved registers. * * * * 3-6 C Cross Compiler * Return registers: r4 for 16-bit return values, and r5r4 for 32-bit return values. The mode registers are never modified by SDCC/ZDXCC except through inline assembly. The circular buffer registers are never accessed or modified except through predefined macros in the header file cbuf.h. The file cbuf.h also has predefined macros to set and clear the cb0 and cb1 bits in %smode. 3.2.2.2 ZDCC Register Usage Register usage by ZDCC is summarized below. Registers r0-r15 are general-purpose registers, a0-a7 are address registers, n0-n7 are index registers, g0-g7 are guard registers and registers beginning with `%' are control registers. * Registers used by the compiler: r0-r15, a0-a7, n0-n7, g0-g7, %fmode, %smode, %amode, %hwflag, %loop0-%loop3, %rpc, %pc, %cb0_beg-%cb3_beg, %cb0_end-%cb3_end. Stack pointer: a7 Parameter registers: r2-r7, a0, a1, a6 Callee preserved registers: r8-r15, g6, g7, a2-a5, a7, n4-n7, %loop2, %loop3 Scratch registers: r0, r1, g0-g5, n0-n3, %loop0, %loop1 Return registers: a0 for pointer values, r4 for 16-bit return values, and r5r4 for 32-bit non-pointer values. * * * * * The mode registers are never modified by ZDCC except through inline assembly. The circular buffer registers are never accessed or modified except through predefined macros in the header file cbuf.h. The file cbuf.h also has predefined macros to set and clear the cb0-cb3 bits in Compiler Conventions 3-7 %amode. Table 3.5 shows the mode bits that may affect the behavior of compiler-generated code. Table 3.5 Mode Register Effect of Mode Bits on Compiler-Generated Code Mode Register Bit Affects Nonintrinsic Code Required Entry Value (before C function call) SDCC ZDXCC ZDCC May be Modified Within Function SDCC ZDXC C %amode ld st cbX %fmode sat1 q152 sre3 mre4 %smode shd5 lis sis cbX6 yes yes yes yes n/a yes no ZDCC SDCC ZDXCC ZDCC yes yes yes no n/a 0 0 0 0 x x x x n/a yes yes yes x 0 0 0 n/a x x 0 no no no yes n/a yes no no yes yes yes yes yes n/a no no no yes no dir7 ddr8 yes yes x x no no 1. Wtih SDCC/ZDXCC, the sat bit of %fmode can affect nonintrinsic code because of the add and subtract instructions. Nonintrinsic code expects unsaturated arithmetic. If you require saturated arithmetic for some intrinsics, it is safest to enable saturation over as small a region of code as possible, because the sat bit also affects adds and subtracts that must not be saturated (e.g. address arithmetic, stack pointer manipulation, counters, etc. ). If you use the -minfer_mac option, the compiler also generates mac and macn instructions, which are also affected by the sat bit. 2. With SDCC/ZDXCC, the q15 mode bit affects nonintrinsic code if the -minfer_mac option is used. 3. The sre bit of %fmode affects nonintrinsic code because of the shra and shra.e instructions. Only perform right shifts of signed variables when the sre bit is cleared. 3-8 C Cross Compiler 4. With SDCC/ZDXCC, the mre mode bit affects nonintrinsic code if the -minfer_mac option is used. 5. This bit is ZSP400 specific and selects/unselects the use of shadow registers. Compiled code operates correctly with either shadow registers or nonshadow registers. 6. For ZSPG2, these bits affect the behavior of r14 and r15. They exist for compatibility with ZSP400. They should never be set in code compiled with the ZDCC. When using SDCC/ZDXCC, to prevent these bits from affecting nonintrinsic code, clear these bits when the portion of code requiring circular buffers is exited. 7. This bit controls whether instructions are fetched from internal or external memory. Compiled code operates correctly when it resides in internal or external memory, though normally it resides in internal memory. 8. This bit controls whether data is fetched from internal or external memory. Compiled code operates correctly when data resides in internal or external memory, though normally data resides in internal memory. Note that data includes the stack, and that compiled code does not operate correctly if global data resides in one memory and the stack resides in another memory. 3.2.3 Conventions Used for Passing Parameters SDCC/ZDXCC's conventions for passing parameters are described below. * * * * * The first three (16-bit) word parameters (scalar type) are passed in registers r4-r6. All other parameters are passed on the stack. A 16-bit value is returned in r4; a 32-bit value is returned in r5r4. A structure is returned using a hidden pointer, which is passed by the caller in r4. A structure is passed using two arguments. The first argument is a pointer to the structure, and the second argument is the structure to be passed. The pointer to the structure is a 16-bit value and can be passed in a register if it is one of the first three word-sized arguments. The second argument, the structure, is passed on the stack. For structures with a size of one or two words, the pointer argument is eliminated. ZDCC's conventions for passing parameters are described below. Parameters are examined from first to last * * A pointer value will be passed in the first unused register in the following list: a0, a1, a6, r5r4, r7r6, r3r2. A 32-bit non-pointer value will be passed in the first unused register in the following list: r5r4, r7r6, r3r2, a0, a1, a6. Compiler Conventions 3-9 * * * * A 16-bit value will be passed in the first unused register in the following list: r4, r5, r6, r7, r2, r3. All other parameters are passed on the stack. A pointer value is returned in a0. A non-pointer 32-bit value is returned in r5r4. A 16-bit value is returned in r4. A structure is returned using a hidden pointer, which is passed by the caller in a0. Note that registers that were skipped so that a 32-bit parameter could be passed can be used later when passing a 16-bit parameter. For example, a function with prototype: void f(int, long, int) will expect its' arguments to be in: r4, r6r7, and r5 respectively. 3.2.4 Run Time Stack The C run time stack grows towards lower addresses in memory. The stack pointer (r12 with SDCC/ZDXCC, a7 with ZDCC) decrements when items are pushed on the stack. The initial memory location of the stack is specified in the initialization file crt0.o. Table 3.6 shows the layout of a function's stack frame. Table 3.6 Stack Frame Layout Callee saved registers %rpc Local variables and temporaries Outgoing arguments (The stack allocates enough space to accommodate any call by the function.) 3-10 C Cross Compiler Table 3.7 shows the two example stack frames for the functions foo and bar, after foo calls bar. Table 3.7 high address Stack Frame Example Callee saved registers of foo locals/temps of foo foo's stack frame max args of all functions called by foo callee saved registers of bar locals/temps of bar low address max args of all functions called by bar bar's stack frame Note that within the body of a function, the stack pointer points to the beginning of the next stack frame. When a function is called, the compiler places arguments into registers, if possible, and puts the remaining arguments in the outgoing arguments of the caller's stack frame. The compiler places any required arguments on the stack from lower to higher addresses. Thus the first argument placed on the stack is the one closest to the callee's stack frame. The function call is made after all the arguments have been properly placed. 3.2.5 Example Code for Function Prologue and Epilogue 3.2.5.1 SDCC/ZDXCC The following is a sample prologue that saves r0-r3, r7-r9, and %rpc and reserves 30 words of space on the stack. Note that with optimization, this code will be reordered with non-prologue code for better scheduling by sdopt. Compiler Conventions 3-11 stdu stdu stu stdu mov stu mov sub r0, r12, -2 r2, r12, -2 r7, r12, -1 r8, r12, -2 r13, %rpc r13, r12, -1 r13, 30 r12, r13 The appropriate epilogue code for the above prologue is shown below. ZSP interrupt routines expect the stack pointer to point to a writable location. This requirement prevents the use of the stack pointer to directly restore the saved registers. Instead, the stack pointer is copied to r6, and r6 is used to restore the saved registers. After all the registers are restored, r6 is copied back to the stack pointer. mov mov add ldu mov lddu ldu lddu lddu add mov ret r6, r12 r13, 31 r6, r13 r13, r6, 1 %rpc, r13 r8, r6, 2 r7, r6, 1 r2, r6, 2 r0, r6, 2 r6, -1 r12, r6 3.2.5.2 ZDCC The following is a sample epilogue that saves r8, r9, a2, and %rpc and reserves 20 words of space on the stack. Note that with optimization, this code will be reordered with non-prologue code for better scheduling pushd mov.e pushd pushd add r8, r8, r8, a2, a7, a7 %rpc a7 a7 -20 The appropriate epilogue code for the above prologue is shown below. add popd popd a7, 20 a2, a7 r8, a7 3-12 C Cross Compiler mov.e popd ret %rpc, r8 r8, a7 3.2.6 Parameter Passing Examples 3.2.6.1 SDCC/ZDXCC In the example below, function foo calls function bar, passing two long (32-bit) arguments from r1r0 and r3r2. The first argument is placed in the stack at r12 + 1, and the second argument is placed at r12 + 3. Function bar has a frame size of 16 and accesses the passed arguments in function foo's outgoing argument stack space. mov add stdu mov add stdu r13, 1 r13, r12 r0, r13, 2 r13, 3 r13, r12 r2, r13, 2 !! The first argument location on the stack !! Store r0 at r12+1 and r1 at r12+2. !! Compute r12+3 and store in r13. !! Store r2 in r12+3 and r3 in r12+4. The function bar retrieves arguments from foo's stack space by loading the values from foo's outgoing argument space. The first word of foo's outgoing arguments is located at r12+(bar's stack space)+1, or r12+(16)+1. mov ldx mov ldx mov ldx mov ldx r13, 17 r0, r12 r13, 18 r1, r12 r13, 19 r2, r12 r13, 20 r3, r12 3.2.6.2 ZDCC The following C code: void callee(int i1, long l1, int i2, long l2, long l3, long *p1, long l4, long l5, long l6) { global = l5+l6; Compiler Conventions 3-13 } void caller() { long a=7; callee(1,2,3,4,5,&a,7,8,9); } The arguments will be passed in the following locations: i1 l1 i2 l2 l3 p1 l4 l5 l6 r4 r7r6 r5 r3r2 a0 a1 a6 stack+1 stack+3 The above code will produce the following calling code sequence: mov std mov mov std std mov mov mov mov mov mov mov mov mov add call a1, 8 a1, a7, 1 a0, 7 a1, 9 a0, a7, 5 a1, a7, 3 a6, a0 r4, 0x1 r6, 2 r7, 0 r5, 0x3 r2, 4 r3, 0 a0, 5 a1, a7 a1, 5 _callee !l5, fifth 32-bit non-pointer parameter passed on stack !l6, !l4, !i1, !l1, sixth 32-bit non-pointer parameter passed on stack fourth 32-bit non-pointer parameter passed in a6 first 16-bit parameter passed in r4 first 32-bit non-pointer parameter passed in r7r6 !i2, second 16-bit parameter passed in r5 !l2, second 32-bit non-pointer parameter passed in r3r2 !l3, third 32-bit non-pointer parameter passed in a0 !p1, first pointer parameter passed in a1 The function callee retrieves l5 and l6 from caller's stack space by loading the values from caller's outgoing argument space. The first word of caller's outgoing arguments is located at a7+(callee's stack space)+1, or a7+(0)+1. mov add ldd ldd a0, a0, r4, r6, a7 1 a0 a7, 3 3-14 C Cross Compiler 3.3 Run Time Environment The compiler run time environment is initialized in the startup file crt0.o on Solaris platforms or crt0.obj on Windows platforms. By default, the startup file is automatically linked by the compiler. The initialization file will fill the bss section with zeroes. The run-time memory map contains three main sections: text, data, and bss, in that order. The heap grows from lower addresses to higher addresses and starts after the bss section. The stack grows from higher to lower addresses, and starts at the address specified by the predefined variable __stack_start - 4, which has a default value of 0xF7FB for SDCC/ZDXCC and 0xFFEFFF for ZDCC. This can be modified as shown below. sdcc -Wl,-defsym,__stack_start=0xd000 test.c 3.4 C Run Time Library Functions The libc.a libraries supplied with the C compiler contain the run time library functions. These functions are equivalent to those found in other C programming environments, having the same names and parameter lists. Thus existing programs that use these functions may be recompiled without any changes. The compiler provides a debugging form of the library, libg.a, which allows you to debug standard library functions. Run Time Environment 3-15 The library functions are grouped into the following categories: * String functions (string.h) bcmp, bcopy, bzero, index, memchr, memcmp, memcpy, memmove, memset, rindex, strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtok. * I/O functions (stdio.h) fopen, fclose, fwrite, fread, fgetc, fputc, fprintf, printf, sprintf, vfprintf, vprintf, vsprintf, getc, putc, getchar, putchar The fprintf and printf functions have been extended to allow printing of the q15 data type. A "%q" format specifier will print a 16-bit value in fixed-point notation. * * * The filehandles stdin, stdout, and stderr are available for use with fwrite, fread, fgetc, fputc, and fprintf. Memory allocation functions (stdlib.h) malloc, free, mbtowc Interprocedural control flow functions (setjmp.h) setjmp, longjmp In the case of I/O functions, the SDK performs file I/O by sending a message to the program running on the host (sdbug400, zsim400, zisim400, zdbug, zdxbug, zsimg2 or zisimg2). These messages will cause the host program to perform the requested file I/O operation. All host programs and all zdbug targets support file I/O. 3.5 N-Intrinsics SDCC N-Intrinsics provide support for DSP instructions. N-Intrinsics are implemented as macros in the header file N_Intrinsic.h. The name of an N-Intrinsic begins with an N_ , followed by a suffix that indicates the operation's data type: _s for int, _l for long, and _h for high-order int of a long. 3-16 C Cross Compiler To use N-intrinsics, add the following line in each of your C files: #include Generated Code mac.acc x, y macn.acc x, y Analogous L-Intrinsic L_maca, L_macb L_macna, L_macnb L_mac2a, L_mac2b L_mula, L_mulb None norm_l norm_s extract_h L_deposit_h L_abs abs_s round L_shla shla Intrinsic Function N_mac(accum acc, int x, int y) N_macn(accum acc, int x, int y) N_mac2(accum acc, long x, long y) mac2.acc x,y N_mul(accum acc, int x, int y) N_muln(accum acc, int x, int y) N_norm_l(int ret, long a) N_norm_s(int ret, int a) N_extract_h(int ret, long a) N_deposit_h(long ret, int a) N_abs_l(long ret, long a) N_abs_s(int ret, int a) N_round_l(long ret, long a) N_shla_l(long ret, int a) N_shla_s(int ret, int a) mul.acc x, y muln.acc x, y norm.e ret, a norm ret, a ret = a[31:16] ret[31:16] = a ret[15:0] = 0 abs.e ret, a abs ret, a round.e ret, a shla.e ret, a shla ret, a N-Intrinsics 3-17 3.5.1 Vector N-Intrinsics The ZDCC compiler also provides N-Intrinsics for common vector operations. They are shown in Table 3.9. The vector N-Instrinsics will produce more efficient code than the equivalent non-vector code. Table 3.9 N-Intrinsic 1 N_vc_mac(accum acc, int *vec1, int inc1, int cnst, int len) N_vc_macn(accum acc, int *vec1, int inc1, int cnst, int len) N_vv_mac(accum acc, int *vec1, int inc1, int *vec2, int inc2, int len) N_vv_macn(accum acc, int *vec1, int inc1, int *vec2, int inc2, int len) Vector N-Intrinsics Functionality 2 for (i=0; i Important: If you use vector N-Intrinsics at optimization level 3 (-O3), you must also use the -fno-inline option. Functions with vector N-Intrinsics must not be inlined, since these intrinsics create labels. If these labels are inlined, they are duplicated and cause an error. 3.5.2 ETSI Functions The SDCC's N-Intrinsics also allow access to processor-supported ETSI functionality, although the interface is different. For example, the ETSI code: y = norm_l(x); can be rewritten with N-Intrinsics as: N_norm_l(y,x); 3-18 C Cross Compiler Another approach that preserves the ETSI defined interface would be to use N_norm_l to implement the ETSI function. For example, norm_l could be implemented as: static inline int norm_l(long src) { int ret; N_norm_l(ret,src); return(ret); } You may implement some ETSI functions can be implemented using NIntrinsics, but you must set mode bits in %fmode accordingly. For example, you can implement the ETSI function L_mac using N_mac, but you must also set the SAT and Q15 mode bits in %fmode. This correspondence between N-Intrinsics and ETSI functions is shown in Table 3.10. Table 3.10 ETSI to N-Intrinsic Mapping fmode1 Register Bits ETSI Function abs_s extract_h L_abs L_deposit_h L_mac L_macN L_msu L_msuN L_mult L_shl mac_r N-Intrinsic N_abs_s N_extract_h N_abs_l N_deposit_h N_mac N_mac N_macn N_macn N_mul N_shla_l N_mac sat x x x x 1 0 1 0 x 1 1 q15 x x x x 1 1 1 1 1 x 1 sre x x x x x x x x x x x mre x x x x 0 0 0 0 0 x 1 N-Intrinsics 3-19 Table 3.10 ETSI to N-Intrinsic Mapping (Cont.) fmode1 Register Bits ETSI Function msu_r mult mult_r norm_l norm_s round N-Intrinsic N_macn N_mul N_mul N_norm_l N_norm_s N_round_l sat 1 x 1 x x x q15 1 1 1 x x x sre x x x x x x mre 1 0 1 x x x 1. 1 = Set, 0 = Cleared, x = Don't Care 3.6 Circular Buffers The cbuf.h header file provides the interface to the circular buffers. The header file's macros generate the necessary assembly instructions. To use a circular buffer, a pointer must be declared, the circular buffer boundaries must be set, and the circular buffer must be enabled. With SDCC/ZDXCC the pointer must be in r14 or r15. register int *pt asm("r14"); set_r14_cbuf(low,high); enable_r14_cbuf; With ZDCC, the pointer must be in a0 - a3. register int *pt asm("a2"); set_cbuf(CBUF_ID,low,high); enable_cbuf(CBUF_ID); CBUF_ID must be A0_CBUF, A1_CBUF, A2_CBUF or A3_CBUF. A circular buffer must have at least 4 ints or 2 longs. Circular buffers can be disabled using the following macros with SDCC/ZDXCC: disable_rn_cbuf; 3-20 C Cross Compiler For ZDCC the macro is: disable_cbuf(CBUF_ID); There are special macros defined within cbuf.h to access the elements in a circular buffer. These macros are the same for all compilers. load_int_cbuf(dst,pt,inc) store_int_cbuf(src,pt,inc) load_long_cbuf(dst,pt,inc) store_long_cbuf(src,pt,inc) The inc parameter determines the number of elements to increment the pointer pt. The inc parameter must be a constant rather than a variable. For load_int_cbuf and store_int_cbuf, inc must be in the range 1-50. For load_long_cbuf and store_long_cbuf, inc must be in the range 1-25. It is legal to access a value pointed to by pt using *pt, so an increment value of 0 is not needed. The dst and src parameters are variables used for the destination and source values, respectively. Note that these parameters are not pointers to a location where the destination/source will be stored/accessed, but to the variables that will actually be stored/accessed. Note: You must disable circular-buffer arithmetic immediately after the final use of pt, because the compiler may reuse the register containing pt for other purposes. The code generated in this case would not expect the register to have circular arithmetic. Because the registers supporting circular-buffer functionality are not saved and restored by function calls/returns, circular buffers should not be used with code containing function calls. 3.7 Accessing Control Registers Macros have been defined in the header file Accessing Control Registers 3-21 read_creg(creg,var) - Puts the value of a control register into var. write_creg(creg,val) - Puts a value, which can be a variable or an immediate, into a control register. The val argument can be made by or-ing together the following masks for the following registers: Macros have also been defined to manipulate specific bits of control registers. bitset_creg(creg,bitnum) bitclear_creg(creg,bitnum) bitinvert_creg(creg,bitnum) The bitnumber and value arguments can be filled with macros which have been defined to the approiate value. The bitnumber and mask to access a specific bit has been defined to "bit name"_[MASK|BIT]. For example, to set the Q15 bit of %fmode, use the following macro: bitset_creg(%fmode,Q15_BIT); 3.8 Q15 Support CC supports the Q15 data type. To use Q15 arithmetic, the q15 mode bit in the %fmode register must be set, as follows: bitset_creg(%fmode,Q15_BIT); The q15 mode bit affects Q15 multiplies and the N-Instrinsics N_mul, N_mac, N_macn, N_mac2, and the vector intrinsics. Q15 arithmetic can be disabled as follows: bitclear_creg(%fmode,Q15_BIT); This release of the SDK does not support Q15 division. The code produced for the Q15 data type is equivalent to that produced for the int data type, except for the following three cases: * The product of two Q15s is calculated with a mul instruction rather than an imul instruction. 3-22 C Cross Compiler * The 16-bit result of a Q15 product is the high-order 16 bits of the result produced by a mul instruction. The 16-bit result of an int product is the low-order 16 bits of the result produced by an imul instruction. The product of two Q15 constants is not simplified by the compiler. * The fprintf and printf functions have been extended to allow printing of the q15 data type. A "%q" format specifier will print a 16-bit value in fixed point notation. 3.9 Inline Assembly Inline assembly that references C variables can be generated by using the asm directive. 3.9.1 Syntax The basic syntax of the asm directive is: asm( "parameterized assembly" : output variable, ... : input expression, ... : explicitly clobbered register, ... ); 3.9.2 Parameterized Assembly The parameterized assembly consists of a text string containing the desired assembly output with parameters that will be replaced with registers or constants according to the arguments in output variable and input expression. The syntax of a parameter is shown in Table 3.11. Table 3.11 Format %n %mn %on Parameter Output Syntax Output register name or constant accumulator name high register name Inline Assembly 3-23 In the table above, n is the index of the desired argument in output variable or input expression. The three formats--%, %m, and %o-- control the way an argument is printed in the generated assembly. For example, a variable of long type that the compiler has placed in r1 and r0 will be printed as r0 when the % format is specified, as a when the %m format is specified, or as r1 when the %o format is specified. 3.9.3 Variables and Expressions The syntax for an output variable and input expression is: "constraint" (expression|variable) A constraint is used to describe the requirements that an instruction places on an argument. For example, an instruction that requires an argument to be in a particular register would put a constraint on that argument to ensure that the argument is placed in an allowed register. In example 3 in Section 3.9.5, "Examples of asm Directive", the acc variable is constrained to be in an accumulator register. The supported constraints are shown in Table 3.12. Table 3.12 Constraint = r e h c n Argument Constraints Effect output variable general-purpose register address register index register accumulator register constant same as indexed argument Availability All compilers All compilers ZDCC ZDCC All compilers All compilers All compilers Note that a constant argument can be used with an r constraint. The SDK copies the constant to a register and uses the register as the argument. You can combine constraints, which can be useful for instructions that allow different types of arguments. For example, the shla instruction can accept either a register or an immediate argument. 3-24 C Cross Compiler The appropriate constraint for this argument would be rn. In example 4 in Section 3.9.5, "Examples of asm Directive", the input parameter is constrained to be either a register or an immediate. Sometimes it is necessary for two arguments to be in the same register. This requirement can be described by constraints. The first argument should be described with whatever constraint is appropriate, and the second argument's constraint must be the index of the first argument. For example, the first argument of the add instruction is an output/input argument. You must list this argument as an output variable and an input expression. The constraint of this argument when it appears as an input expression should be the index of the argument when it appears as an output variable. In example 3 in Section 3.9.5, "Examples of asm Directive", the output argument and the first argument illustrate this technique. 3.9.4 Explicitly Clobbered Registers The syntax for an explicitly clobbered register is: "register name" This entry tells the compiler that the assembly code generated will clobber the specified register. Thus the generated assembly code may use the specified register for scratch purposes. 3.9.5 Examples of asm Directive The examples in the subsections below illustrate the usage of the asm directive. 3.9.5.1 Example 1 asm("norm.e %0, %1": "=r" (ret) : "r" (a)); The example shown above has one output argument, ret, and one input expression, a. If the variable ret is in r0 and the variable a is in r4, this directive produces: norm.e r0, r4 Inline Assembly 3-25 3.9.5.2 Example 2 asm("abs r5, %1\n\tst r5, %0" : : "e" (addr), "r" (val) : "r5"); The example shown above stores the absolute value of val at addr. Two instructions are generated by this directive. There are two input expressions and no output arguments. Note that register r5 is clobbered by this directive. If addr is in a0 and val is in r15, this directive produces: abs r5, r15 st r5, a0 3-26 C Cross Compiler 3.9.5.3 Example 3 asm("mac.%m0 %2, %o2" : "=c" (acc) : "0" (acc), "r" (val)); The example above adds the 32-bit product of the high and low 16 bits of val to acc. Note that the high part of val is obtained with the %o2 operand and that the accumulator is printed with the %m0 operand. Also note that acc is both an input and an output argument, and that the constraint for acc when it appears as an output argument is c, an accumulator, and when it appears as an input argument is 0, which tells the compiler that these two arguments must be in the same location. If acc is in r0 and val is in r3r2, the following code is generated: mac.a r2, r3 3.9.5.4 Example 4 asm("mov %%smode, %0" : : "rn" (val)); The example shown above sets %smode to val. Note that %smode is not specified as a clobbered register, because %smode has no meaning to the compiler. If val is a symbolic constant with the value 3, the following code is generated: mov %smode, 3 You can find additional examples of using the asm directive in the header file N_Intrinsic.h. 3.9.5.5 Example 5 asm("bits %smode, 7"); The example shown above sets bit 7 in %smode. This example illustrates the general rule that if the assembly statement contains an argument (as in Example 4, which contains the argument %0), a reference to a register must contain an additional per cent (%) sign. Example 5 contains no argument, so a single % preceding smode is used. Inline Assembly 3-27 3.9.6 Optimization of Inline Assembly For purposes of optimization, the compiler assumes that inline assembly has no effect except to modify the output variables. Thus inline assembly can be removed by optimization if none of the output variables is subsequently used. Inline assembly that must not be deleted or significantly moved should contain the keyword volatile following the asm directive, as shown below. asm volatile("bits %smode, 7"); The volatile keyword is implicit for inline assembly with no output variables. Thus, the use of volatile in the above example is redundant. 3.10 Assembly Optimizer and Handwritten Assembly The assembly optimizers can be used to automatically generate the prologue and epilogue for an assembly function and then to schedule the entire function. sdopt -asm assemblyfile The output will be placed in standard output. The assembly optimizers expect input of the following format: !PROLOGUE( This will be transformed by the assembly optimizer to: .set REGSAVE_SIZE_ All registers that must be preserved according to the C calling convention will be preserved. Note that the name REGSAVE_SIZE_ 3-28 C Cross Compiler !PROLOGUE and !EPILOGUE markers will be copied without modification. 3.11 Debugging Options You can debug code compiled using the GCC-supplied -g option, which generates debugging information. You can attempt debugging with optimization turned on, though optimization makes debugging difficult. When debugging optimized code, use the -mno_sdopt option, because sdopt, zdxopt and zdopt do not preserve the location of debugging information. Using the -g option with optimization modifies the code generated in two ways. First, the debugging version of the C library is linked, rather than the optimized version. Second, leaf functions save and restore %rpc (without the -g option, this save and restore is removed by optimization). The -g option saves and restores this register, because the debugger requires it to examine the call stack. 3.12 Code Statistics CC creates four labels and symbols that are useful in analyzing the code generated by the compiler. Every function will have a label placed on its first instruction and after its last instruction with the following formats: __FUNC_START_ Debugging Options 3-29 3.13 Example Compilations 3.13.1 Example 1 cc test.c -Tdata=0x1 This command invokes the C compiler, assembler, and linker and produces an executable file with the default name a.out. The -Tdata=0x1 command places the data at address 0x1 to prevent a NULL pointer from being a valid pointer. 3.13.2 Example 2 cc -c test.c This command invokes the C compiler and assembler only, producing an object file with the default name test.obj (Windows) or test.o (UNIX). 3.13.3 Example 3 cc -S test.c This command invokes the C compiler only, producing an assembly file with the default name test.s. 3.13.4 Example 4 cc -O3 test.c This command invokes the C compiler with the highest level of optimization, that is, including all level -O2 optimizations, as well as function inlining and loop unrolling. The assembler and linker are also invoked, and the output is an executable file with the default name a.out. 3-30 C Cross Compiler Chapter 4 Assembler The SDK Assembler (SDAS/ZDAS) is based on the GNU assembler, AS, from the Free Software Foundation. It is described in Using AS: The GNU Assembler, by Dean Elsner, et. al., Free Software Foundation, January 1994. The description of SDAS/ZDAS in this chapter, for the most part, includes only the differences from AS. SDAS is the assembler for the ZSP400 architecture. ZDAS is the assembler for the ZSPG2 architecture. In this chapter, unless otherwise noted, SDAS refers to both the ZSP400 and ZSPG2 assemblers. The assembler is invoked from the shell using the following command: sdas [options] sourcefile SDAS processes an assembly source file with the .s file extension and produces a relocatable object file in ELF format with the default file extension .obj (Windows) or .o (UNIX). 4.1 Assembly Language Syntax The basic format of a SDK assembly language statement is: [ label: ] [ statement ] [ !comment ] Labels are identifiers that start at the beginning of a line, with no leading spaces or tabs, and end with a colon. Identifiers begin with a letter (case is significant) or an underscore, and can continue with more letters, digits, and underscores. Assembly language instructions can be on the same line as a label. Examples: Start: start: !"Start" is a label !"start" is another (different) label ZSP SDK Software Development Kit 4-1 loop: End bnz start add r0, r1 bnz Start: !"start" is a label reference !"loop" is a label ! Illegal reference (extra colon) ! Illegal label (missing colon) Symbols beginning with `L are locally resolved, and are therefore not ' visible to the linker or to other modules. Assembler statements can be assembler directives or assembly language instructions. Assembler directives start with a period (`.'). Comments start with an exclamation mark (!) and continue until the end of the line. The symbol `#' at the beginning of the line indicates that it is a comment. Note that files with the .S extension can be assembled using sdcc, which causes the C preprocessor to run before the assembler. This enables users to use C-style comments and #defines in their assembly code. However using a -g option will not cause any debug symbol generation, since the source file is an assembly program. To turn on debug information for an assembly program with a .S extension, you can use sdcc with the -Wa and -dbg options (the -dbg option is described in Section 4.1.1.4, "Debugging Option (-dbg)," page 4-3). All assembly programs must be contained within a section. Putting .section ".text", "ax" before any assembly code ensures that the code gets assembled into the .text section. Please refer to the GNU assembler manual for more information on the section syntax and flag definitions. 4.1.1 Assembler Options Please refer to the GNU assembler manual for a full description of all options available to the assembler. A few of the more frequently-used options as well as the options specific for the SDK are described below. 4.1.1.1 Suppress warnings (-W) This options prevents warnings from the assembler from being displayed on the screen. 4-2 Assembler 4.1.1.2 Output file (-o) Using -o objfile assembles the output into the object file specified. By default, if you do not use the -o option, the resulting object file is named a.out. 4.1.1.3 Include path (-I) The -I dir option is used to add the specified directory to the search list used by .include directives. 4.1.1.4 Debugging Option (-dbg) The -dbg option adds debugging information to the executable file, which allows you to debug the source file rather than the disassembled text. The usage is: sdas -dbg test.s where test.s is the name of the assembly file. 4.1.2 Assembler Directives The following subsections describe some frequently-used assembler directives, as well as those that are specific to the SDK assembly language. 4.1.2.1 .walign The .walign directive aligns the location counter on the next word boundary specified by an integer argument. If the location counter is already aligned, no action is taken. Intervening words are filled with nop instructions. For example, .walign 32 4.1.2.2 .wspace The .wspace directive allocates space in a segment as specified by an integer argument. The location counter is incremented, regardless of alignment. For example, .wspace 7 ! Increment the location counter by seven. ! Align to the next 32-word boundary. Assembly Language Syntax 4-3 An optional fill value can also be given. If no fill value is given, the space will be filled with zeroes. .wspace 7, 0xd800! Create 7 words of 0xd800 4.1.2.3 .word The .word directive allows a user to specify zero or more comma separated values to be assembled into memory. 4.1.2.4 .global The .global directive is used to declare a global symbol. If this directive is not used, a symbol defined in a partial program is visible only within its scope. The .global directive makes the symbol visible to the linker. 4.1.2.5 .section The .section directive assembles the code following it into the section name specified. Example: .section, ".text", "ax" This defines a section named ".text" - the characters following it tell the assembler that the code following the directive is allocatable and is a part of the instruction memory. Please refer to the GNU assembler manual for more information. Although GNU assembler documentation says unnamed sections go to the default .text section, it is necessary to specify sections explicitly for the ZSP SDK tools. 4.1.3 Assembler Special Cases For all instructions that require a register pair, the even register must be specified as the operand. For the ZSP400 assembler only, If an odd register is specified, the even register of the register pair is used as the actual operand in the instruction, and the assembler displays a warning message. With the ZSPG2 assembler, zdas, an odd register will not be converted to an even register and an error will be message will be shown. 4-4 Assembler For the ZSP400 architecture, a target function must be placed at an even address. If the value is odd, an error message is displayed. A function can be forced to start on an even address by using the .walign 2 directive. For the ZSPG2 architecture, there are no alignment requirements for call targets. Assembly Language Syntax 4-5 4-6 Assembler Chapter 5 Linker The SDK Linker (SDLD/ZDLD) is based on the GNU linker, LD, from the Free Software Foundation. LD is described in Using LD: The GNU Linker, by Steve Chamberlain, Free Software Foundation, January 1994. SDLD is the linker for the ZSP400 architecture. ZDLD is the linker for the ZSPG2 architecture. Unless otherwise noted, SDLD refers to both the ZSP400 and ZSPG2 linkers. The linker processes the object files generated by the assembler (designated with the .obj extension on Windows or .o extension on UNIX) and produces an executable file in ELF format with the default name a.out. The linker is invoked from the shell using the following command: sdld [options] sourcefile 5.1 Sections By default, the linker generates .text, .data and .bss sections. The .text sections contains code, .data contains data, and .bss contains uninitialized data. If there are additional user-defined sections specified in the linker script file, the linker will generate them also. By default, .bss follows .data in Data memory unless relocated using a linker script command. The following section names have special meaning only on the ZSP400 linker: * * .exttext_0 through .exttext_15 .extdata_0 through .extdata_15 ZSP SDK Software Development Kit 5-1 Code or data in these sections is placed in the appropriate external instruction or data memory, with the particular external page selected by the number in the section name. On the ZSP400 architecture, the offset of a call immediate instruction must be even. If the assembler cannot resolve this offset, the linker will. If the offset is odd, the linker displays an error message. Because the assembler will automatically align call immediate instructions on an even address, this error occurs only if the call target was on an odd address. To resolve this error, align the call target on an even address, using the .walign 2 directive. 5.1.1 Symbols By default, program execution begins at __start. The entry point can be altered by specifying an alternate address, using the -e option. For example, the following command will cause execution to begin at address 0xabcd: sdld -e 0xabcd The C stack region will always be set to the internal data memory. The linker uses four symbols for stack-range checking: * * * * __stack_start: beginning of C stack, default setting is 0xF7FF with SDLD and 0xFFEFFF with ZDLD. __stack_end: ending address of C stack __stack_size.linker_defined: stack size calculated by linker __stack_size.user_required: user required stack size set in command line option You can inspect the values of these symbols in the map file. The value of the symbol __stack_start or __stack_end can be set in a linker script file or by using the command-line option defsym sym=Value. The user-required stack size can be set using the command-line option stack_size=Value. The linker will report an error when the stack size is inadequate. 5-2 Linker 5.1.2 Linker command file A linker command file (also called a linker script file) is a file containing linker commands that explicitly define symbols and locate sections in memory. A linker command file can be specified when the linker is invoked. An example linker command file is shown below. SECTIONS { .text 0x2000: {*(.text)} .data 0x3000: {*(.data)} vectors 0x0000: {*(vectors)} } The example above declares the output sections .text, .data, and vectors. Each output section is formed by the corresponding input sections from all files (as indicated by the `*'). Refer to the GNU ld man page for more information. 5.1.3 Linker options The following subsections describe some frequently-used linker options, as well as those that are specific to the SDK assembly language. Option -T linkercommandfile -o outputfile -l archive Description Replaces the linker's default script file with the specified linkercommandfile. Names the output file. By default, the output file name is a.out. Adds archive file archive to the list of files to link. The linker will search for files libarchive.a for every archive specified using this option. Adds searchdir to the list of directories to search for archive libraries and linker scripts. Multiple paths can be specified by using the L option multiple times. Prints the link map to stdout. A link map contains information on the mapping of symbols. -L searchdir -M Sections 5-3 Option --defsym symbol=expression Description Creates a global symbol in the output file containing the absolute address specified by the expression. This option can be used multiple times to create multiple symbols. Valid formats for expression are hexadecimal constants or the names of existing symbols. Locate the .bss section at the address specified by addr. Locate the .text section at the address specified by addr. Locate the .data section at the address specified by addr. -Tbss addr -Ttext addr -Tdata addr 5-4 Linker Chapter 6 Utilities This chapter describes the SDK utility programs. The SDK provides additional utilities for manipulating files that are generated by the tools during project creation. These SDK-specific utilities, described in Table 6.1, replace their GNU counterparts. Tools for the ZSP400 architecture start with an "sd" prefix. Tools for the ZSPG2 architecture start with a "zd" prefix. Unless otherwise specified, the description of a utility applies to both the ZSP400 and ZSPG2 versions of the tools. Table 6.1 SDK Utilities and GNU Counterparts GNU Equivalent ar nm Utility sdar zdar sdnm zdnm Function Creates, modifies, and extracts files from an archive. Lists symbols from object files. Displays information from object files. Generates an index for an archive. Prints the printable characters in the files. Lists section sizes and total size of object file. Discards symbols from object files. Copies and translates object files. sdobjdump objdump zdobjdump sdranlib zdranlib ranlib sdstrings strings zdstrings sdsize zdsize sdstrip zdstrip size strip sdobjcopy objcopy zdobjcopy ZSP SDK Software Development Kit 6-1 6.1 sdar Format sdar [-]p[mod [relpos]] archive [member...] Description sdar creates, modifies, and extracts from archives. An archive is a single file holding a collection of other files in a structure that allows you to retrieve the original individual files (called members of the archive). The original files' contents, mode (permissions), timestamp, owner, and group are preserved in the archive, and can be restored on extraction. When you specify the modifier s, sdar creates an index to the symbols defined in relocatable object modules in the archive. Once created, this index is updated in the archive whenever sdar makes a change to its contents (save for the `q' update operation). An archive with such an index speeds up linking to the library, and allows routines in the library to call each other without regard to their placement in the archive. You may use `sdnm -s' or `sdnm --print-armap' to list this index table. If an archive lacks the table, another form of ar called sdranlib can be used to add just the table. Options 6-2 Utilities The p keyletter specifies what operation to execute. It may be any of the following, but you must specify only one of them: Table 6.2 Option d sdar p Keyletter Options Description Deletes modules from the archive. Specify the names of modules to be deleted as member...; the archive is untouched if you specify no files to delete. If you specify the `v' modifier, ar lists each module as it is deleted. Prints the specified members of the archive, to the standard output file. If the `v' modifier is specified, show the member name before copying its contents to standard output. If you specify no member arguments, all the files in the archive are printed. Inserts the files member... into archive (with replacement). This operation differs from `q' in that any previously existing members are deleted if their names match those being added. If one of the files named in member... does not exist, ar displays an error message, and leaves undisturbed any existing members of the archive matching that name. By default, new members are added at the end of the file; but you may use one of the modifiers `a', `b', or `i' to request placement relative to some existing member. The modifier `v' used with this operation elicits a line of output for each file inserted, along with one of the letters `a' or `r' to indicate whether the file was appended (no old member deleted) or replaced. Displays a table listing the contents of archive, or those of the files listed in member... that are present in the archive. Normally only the member name is shown; if you also want to see the modes (permissions), timestamp, owner, group, and size, you can request that by also specifying the `v' modifier. If you do not specify a member, all files in the archive are listed. If there is more than one file with the same name (say, `fie') in an archive (say `b.a'), `ar t b.a fie' lists only the first instance; to see them all, you must ask for a complete listing--in our example, `ar t b.a'. Extracts members (named member) from the archive. You can use the `v' modifier with this operation, to request that ar list each name as it extracts it. If you do not specify a member, all files in the archive are extracted. p r t x A number of modifiers (mod) may immediately follow the p keyletter, to specify variations on an operation's behavior: sdar 6-3 Table 6.3 Option f sdar p Keyletter Modifiers Description Truncates names in the archive. GNU ar will normally permit file names of any length. This will cause it to create archives which are not compatible with the native ar program on some systems. If this is a concern, the `f' modifier may be used to truncate file names when putting them in the archive. Preserves the original dates of members when extracting them. If you do not specify this modifier, files extracted from the archive are stamped with the time of extraction. Normally, `ar r'... inserts all files listed into the archive. If you would like to insert only those of the files you list that are newer than existing members of the same names, use this modifier. The `u' modifier is allowed only for the operation `r' (replace). In particular, the combination `qu' is not allowed, since checking the timestamps would lose any speed advantage from the operation `q'. Quick append at end of files o u q 6-4 Utilities 6.2 sdstrip Format sdstrip [-R sectionname | --remove-section=sectionname] [-s | --strip-all] [-S | -g | --strip-debug] [-N symbolname | --strip-symbol=symbolname] [-o file] [-p |--preserve-dates] [--help] objfile ... Description sdstrip discards all symbols from the object files objfile. The list of object files may include archives. At least one object file must be specified. sdstrip modifies the files named in its argument, rather than writing modified copies under different names. Options sdstrip 6-5 Table 6.4 Option --help sdstrip Options Description Shows a summary of the options to strip and exit. Removes the named section from the file. You may give this option more than once. Note that using this option inappropriately may make the object file unusable. Removes any section named sectionname from the output file. You may give this option more than once. Note that inappropriate use of this option inappropriately may make the output file unusable. Removes all symbols. Removes debugging symbols only. Removes symbol symbolname from the source file. You may give this option more than once, and may be combined with other strip options. Puts the stripped output in file, rather than replacing the existing file. If you use this argument, you can specify only one objfile argument. -R sectionname | --remove-section=sectionname -R sectionname | --remove-section=sectionname -s | --strip-all -S | -g | --strip-debug -N symbolname | --strip-symbol=symbolname -o file 6-6 Utilities 6.3 sdranlib Format sdranlib archive Description The sdranlib utility generates an index to the contents of an archive and stores it in the archive. The index lists each symbol defined by a member of an archive that is a relocatable object file. You may use `sdnm -s' or `sdnm --print-armap' to list this index. An archive with such an index speeds up linking to the library and allows routines in the library to call each other without regard to their placement in the archive. sdranlib 6-7 6.4 sdnm Format sdnm [-g | -s | -A | -o | -u | -l ] objfile Description The sdnm utility lists the symbols from object files objfile. If no object files are given as arguments, sdnm assumes the file a.out. Options Table 6.5 Option -A | -o | --print-file-name sdnm Options Description Precedes each symbol by the name of the input file where it was found, rather than identifying the input file once only before all of its symbols. Displays only external symbols. Prints the symbols in the order they are encountered rather than sorting them first. When listing symbols from archive members, includes the index, which is a mapping (stored in the archive by ar or ranlib) of what modules contain definitions for what names. Uses radix as the radix for printing the symbol values. It must be `d' for decimal, `o' for octal, or `x' for hexadecimal. Displays only undefined symbols (those external to each object file). Uses debug information to display filename and line number for symbols. -g | --extern-only -p | --no-sort -s | --print-armap -t radix | --radix=radix -u | --undefined-only -l | --line-numbers 6-8 Utilities 6.5 sdsize Format sdsize [ -A |B | --format=compatibility ][ -x | -radix=number ][ objfile... ] Description The sdsize utility lists the section sizes, and the total size, for each of the object or archive files objfile in its argument list. By default, one line of output is generated for each object file or each module in an archive. objfile... are the object files to be examined. If none are specified, the file a.out will be used. Options Table 6.6 Option -A | -B | --format=compatibility sdsize Options Description Using one of these options, you can choose whether the output from sdsize resembles output from System V UNIX size (using `-A', or `--format=sysv'), or Berkeley Software Distribution (BSD) size (using `-B', or `-format=berkeley'). The default is the one-line format similar to BSD format. Shows a summary of acceptable arguments and options. Using one of these options, you can control whether the size of each section is given in decimal (`-d', or `-radix=10'); octal (`-o', or `--radix=8'); or hexadecimal (`-x', or `--radix=16'). In `--radix=number', only the three values (8, 10, 16) are supported. --help -d | -o | -x | --radix=number Example Here is an example of formatting the output from sdsize closer to System V conventions: sdsize --format=SysV file1 file1 : sdsize 6-9 section .text .data .bss Total size 294880 81920 11592 388392 addr 8192 303104 385024 6-10 Utilities 6.6 sdstrings Format sdstrings [-min-len] [-n min-len] [-t radix] [--print-file-name] [--bytes=min-len][--radix=radix] file... Description For each file given, the sdstrings utility prints the printable character sequences that are at least 4 characters long (or the number given with the options below) and are followed by an unprintable character. By default, only strings from the initialized and loaded sections of object files are printed; for other types of files, it prints the strings from the entire file. sdstrings is mainly useful for determining the contents of nontext files. Options Table 6.7 Option -f | --print-file-name -min-len | -n min-len | --bytes=min-len -t radix | --radix=radix sdstrings Options Description Prints the name of the file before each string. Prints sequences of characters that are at least min-len characters long, instead of the default 4. Prints the offset within the file before each string. The single character argument specifies the radix of the offset:`o' for octal, `x' for hexadecimal, or `d' for decimal. sdstrings 6-11 6.7 sdobjdump Format sdobjdump [ -d | --disassemble ] [ -f | --file-headers ] [ -j section | --section=section ] [ -t | --syms ] [ -h | --section-headers ] [ --start-address=address ] [ --stop-address=address ] [ --help ] objfile... Description The sdobjdump utility displays information about one or more object files. The options control what particular information to display. This information is most useful to programmers who are working on the compilation tools, as opposed to programmers who just want their program to compile and work. objfile... are the object files to be examined. When you specify archives, objdump shows information on each of the member object files. Options The long and short forms of options, shown here as alternatives, are equivalent. At least one option from the list must be given. 6-12 Utilities Table 6.8 Option sdobjdump Options Description Displays the assembler mnemonics for the machine instructions from objfile. This option only disassembles those sections which are expected to contain instructions. Displays summary information from the overall header of each of the objfile files. Displays summary information from the section headers of the object file. You may relocate file segments to nonstandard addresses, for example by using the -Ttext, -Tdata, or -Tbss options to ld. Prints a summary of the options to objdump and exit Displays information only for named section. Starts displaying data at the specified address. This affects the output of the -d, -r and -s options. Stops displaying data at the specified address. This affects the output of the -d, -r and -s options. Prints the symbol table entries of the file. This is similar to the information provided by the `nm' program. -d | --disassemble -f | --file-header -h | --section-header | --header --help -j name | --section=name --startaddress=address --stop-address=address -t | --syms sdobjdump 6-13 6.8 sdobjcopy Format sdobjcopy [ -O bfdname | --output-target=bfdname ] [ -b byte | --byte=byte ] [ -i interleave | --interleave=interleave ] [ --gap-fill=val ] [ --pad-to=address ] [ --set-start=val ] [ --adjust-start=incr ] infile [outfile] Description The sdobjcopy utility copies the contents of an object file to another object file. It uses the GNU BFD Library to read and write the object files. It can write the destination object file in a format different from that of the source object file. The exact behavior of sdobjcopy is controlled by command-line options. sdobjcopy generates S-records if you specify an output target of `srec' (use `-O srec'). sdobjcopy generates binary output if you specify an output target of `binary' (use `-O binary'). sdobjcopy generates a raw binary file if you specify an output target of `binary' (e.g., use `-O binary'). When sdobjcopy generates a raw binary file, it will essentially produce a memory dump of the contents of the input object file. All symbols and relocation information will be discarded. The memory dump will start at the load address of the lowest section copied into the output file. When generating an S-record or a raw binary file, it may be helpful to use `-S' to remove sections containing debugging information. In some 6-14 Utilities cases `-R' will be useful to remove sections which contain information which is not needed by the binary file. infile outfile The source and output files, respectively. If you do not specify outfile, objcopy creates a temporary file and destructively renames the result with the name of infile. Options Table 6.9 Option -O bfdname | --output-target=bfdname -b byte | --byte=byte sdobjcopy Options Description Write the output file using the object format bfdname. Keep only every byteth byte of the input file (header data is not affected). byte can be in the range from 0 to interleave-1, where interleave is given by the -i or --interleave option, or the default of 4. This option is useful for creating files to program ROM. It is typically used with an srec output target. Copy only one out of every interleave bytes. Select which byte to copy with the -b or --byte option. The default is 4. objcopy ignores this option if you do not specify either -b or --byte. Fill gaps between sections with val. This operation applies to the load address (LMA) of the sections. It is done by increasing the size of the section with the lower address, and filling in the extra space created with val. Pad the output file up to the load address address by increasing the size of the last section. The extra space is filled in with the value specified by --gap-fill (default zero). Set the address of the new file to val. Not all object file formats support setting the start address. -i interleave | -interleave=interleave --gap-fill val --pad-to address --set-start val sdobjcopy 6-15 6-16 Utilities Chapter 7 ZISIM Simulator This chapter describes the SDK ZSP architecture simulator. The ZSP SDK functional-accurate simulator, ZISIM, simulates the behavior of the LSI40xZ series of ZSP devices, ZSP400, and ZSPG2 architecture-based designs at the architectural level, including the memory model, the operand register file, and the control register file. 7.1 Using ZISIM ZSIM can be accessed as a target through the debugger or as a standalone program. This chapter describes the interface to ZISIM as a standalone program. ZISIM can be used in batch mode or interactively, as described in the following subsections. The commands supported in both modes of operation are described in Section 7.2, "ZISIM Commands," page 7-4. 7.1.1 Batch Mode The simulator can be invoked in batch mode from the command line using the -exec option, as shown below. % zisim400 executeable_file -exec [options] for ZSP400 architecture % zisimg2 executable_file -exec [options] for ZSPG2 architecture The simulator can also be invoked in batch mode using a script file containing ZSIM commands that load, execute, and gather results for a specified executable. Script files may contain any valid ZISIM commands. Comments must be preceded by the comment specifier (#). ZISIM ignores all commands between the # character and the end of line. ZISIM also ignores empty lines. ZSP SDK Software Development Kit 7-1 A simple script file that turns-on instruction tracing and then executes the program test.exe is shown below. load test.exe enable trace write run 100000 exit Assuming the file batch.scr contains the commands shown above, you can generate a trace file for test.exe as follows: % zisim400 -s batch.scr > test.trace (Unix for ZSP400 architecture) % zisimg2 -s batch.scr > test.trace (Unix for ZSPG2 architecture) C:\zisim400 -s batch.scr > test.trace (Windows for ZSP400 architecture) C:\zisimg2 -s batch.scr > test.trace (Windows for ZSPG2 architecture) Refer also to Section 7.2.21, "script," page 7-15. 7.1.2 Interactive Mode In interactive mode, ZISIM is invoked from the shell using the following command: zisim400 [executable_file] [options] zisimg2 [executable_file] options An executable file may or may not be specified, followed by zero or more command-line options separated by spaces The executable file is a ZSP binary file generated using the SDK compiler, assembler, and linker tools, as explained in other chapters of this document. ZISIM processes the source file according to the specified command-line options (refer to Table 7.1). If no options are specified, ZISIM initializes itself, then prompts the user with the ZISIM prompt: zisim{1}> The simulator is now ready to accept and respond to ZISIM commands, which are described in Section 7.2, "ZISIM Commands,". An executable file may be loaded from within ZISIM using the load exe command. 7-2 ZISIM Simulator An example interactive simulation session is described in Section 7.4, "Example Session Using ZISIM". Refer also to the description of using ZISIM use as the target of the SDK's Debugger in Section 9.2.1, "Functional-Accurate Simulator Connection." Table 7.1 Option -c NUM ZISIM Command-line Options Description Limits number of executed instructions to NUM. By default, NUM = 2000000000. Execution continues until a breakpoint is reached or the number of executed instructions hit the limit. Use this option to ensure termination of an algorithm. Prints brief usage summary. Initializes an architectural control (mode) register with specified value. Note that the control register is written without its usual percent (%) sign, and there are no spaces around the equal sign (=). For example, the option to set %SMODE control register is: -i smode=0x1234. The option to set r0 register is -i r0=0x9876. Refer to Appendix B, "ZSP400 Control Registers" for information on ZSP400 core-based device control registers. Enables memory trace. ZISIM prints a trace of the execution program to standard output whenever a write to a memory occurs. The format of this output is similar to option -t. Fetches instructions from external ROM space. If you do not specify this option, instructions are fetched from internal ROM space. ROM is mapped from 0xf800 to 0xffff. This option is specific to zisim400. Displays data in specified radix, either decimal or hexadecimal. Enables register trace. All the architectural registers will be displayed after executing an instruction. Reads all the simulator commands from file. Enables flow trace. ZISIM prints a trace of the executing program to standard output. The information printed includes the instruction sequence number, instruction address, the disassembled instruction and operands, and the resulting architectural state. Example output for the -t option is shown in Section 7.4, "Example Session Using ZISIM," page 7-24. Invokes the simulator in noninteractive mode. Prints version number and exit. -h -i mode_register=value -m -noiboot -radix {dec|hex} -reg -s sourcefile -t -exec -v Using ZISIM 7-3 7.2 ZISIM Commands This section describes commands recognized by the ZISIM command line. Table 7.2 provides a brief summary of commands. The output of any ZISIM command can be sent to a file using the standard redirection identifier (>). For example, the command show attr > filename dumps the output of the show command to filename. Table 7.2 Command alias clear ZISIM Command Summary Modifier - break dmem imem stats Argument [tag command_sequence] breakpoint_number {int | ext} addr size {int | ext} addr size - breakpoint {mem | reg | write} Description Creates alias (tag) for command sequence. Clears specified breakpoint. Clears internal or external data memory. Clears internal or external instruction memory. Clears statistics information. Disables specified breakpoint. Disables run-time instruction tracing. disable break trace dump dmem imem {int | ext} filename addr size Dumps internal or external data memory range to a text file. {int | ext} filename addr size Dumps internal or external instruction memory range to a text file. breakpoint_number {mem | reg | write} - {int | ext} addr size value {int | ext} addr size value Enables breakpoint. Enables run-time instruction tracing. Exits simulation session. Fills internal/external data memory range with value. Fills internal/external instruction memory range with value. enable break trace exit fill - dmem imem (Sheet 1 of 3) 7-4 ZISIM Simulator Table 7.2 Command help load ZISIM Command Summary (Cont.) Modifier - dmem exe imem Argument {category | command} Description Prints list of commands in a category or command usage. {int | ext} filename addr size Loads internal/external data memory from file. filename Loads ZSP executable into instruction memory from file. {int | ext} filename addr size Loads internal/external instruction memory from file. {hard | soft} [number_of_instructions] filename {history | radix | run} value pc addr symbol label register value Resets simulator. Runs for specified number of simulation instructions. Loads and execute ZISIM script file. Assigns value to specified attribute. Creates a new breakpoint at the specified PC address. Creates a new breakpoint at the specified label. Assigns value to specified register. reset run script set - - - attr break break reg (Sheet 2 of 3) ZISIM Commands 7-5 Table 7.2 Command show ZISIM Command Summary (Cont.) Modifier attr bits break dmem imem reg stats trace Argument Description {run | history | radix | version} Shows value of the specified attribute. register - {int | ext} addr size {int | ext} addr size {category | reg}... [opcode] - - alias Displays the bit-level states for the specified register. Displays list of defined breakpoints. Shows contents of a region of internal/external data memory. Shows contents of a region of internal/external instruction memory. Shows contents of register or register set. Shows current run-time statistics. Shows trace information during simulation. Advances simulation by one instruction. Same as run 1. Deletes alias. step unalias - - (Sheet 3 of 3) Table 7.3 Command set ZISIM400 specific commands Modifier Argument size [dmem|imem] size Description Set internal instruction or internal data memory size starting from 0. Default size is maximum value of 0xf800 words. Show size of internal instruction or data memory show size [dmem|imem] 7-6 ZISIM Simulator Table 7.4 Command set ZISIMG2 specific commands Modifier size Argument [dmem|imem] [int|ext] beg_value end_value Description Set the size of internal/external instruction or data memory starting from beg_value to end_value including the boundary. Each memory block could overlap one another. Default value for each of them is from 0 to 0x00ffffff words. Show the current size of internal/external instruction or data memory. show size [dmem|imem] [int|ext] 7.2.1 alias The alias command allows the user to create ZISIM commands by aliasing new commands to existing commands or sequences of commands. Sequences of commands must be contained in quotes and separated by semicolons. Issuing the alias command without arguments shows all current aliases. Format alias tag command_sequence ZISIM Commands 7-7 Examples zisim{32} alias r0 show reg r0 zisim{32} alias adv "step ; show pipe ; show reg gpr" zisim{32} alias adv step ; show pipe ; show reg gpr r0 show reg r0 zisim{33} 7.2.2 clear break This command deletes a breakpoint from the current list of defined breakpoints. The breakpoint number is assigned when a breakpoint is set. Use the show break command to display a list of breakpoints. Format clear break breakpoint_number Example zisim{32} clear break 5 7.2.3 clear dmem This command clears the contents of internal or external data memory. User specifies internal or external memory, the starting address, and the size of the region to clear. Format clear dmem {int|ext} addr size Example zisim{32} clear dmem int 0x1000 0x0100 7.2.4 clear imem This command clears the contents of internal or external instruction memory. User specifies internal or external memory, the starting address, and the size of the region to clear. Format clear imem {int|ext} addr size 7-8 ZISIM Simulator Example zisim{32} clear imem ext 0x7000 0x1000 7.2.5 clear stats This command clears all run-time statistic information. Format clear stats 7.2.6 disable break This command disables a breakpoint from the list of active breakpoints. Use the show break command to display a list of current breakpoints. Format disable break breakpoint_number Example zisim{32} disable break 4 7.2.7 disable trace This command disables specified trace. See the enable trace command for a description of the trace types. Format disable trace {mem|reg|write} Examples zisim{32} disable trace pipe zisim{32} disable trace reg 7.2.8 dump dmem This command generates a text file representing the contents of the specified address range of internal or external data memory. The user specifies internal or external memory, the starting address, and the size of the region to dump. ZISIM Commands 7-9 Format dump dmem {int|ext} filename addr size Example zisim{32} dump dmem ext data.dat 0x0000 0xffff % cat data.dat 0000 /* 0x0000 */ 0000 /* 0x0001 */ 0000 /* 0x0002 */ 0000 /* 0x0003 */ 0000 /* 0x0004 */ 0000 /* 0x0005 */ 0000 /* 0x0006 */ ... 28e2 /* 0x00fd */ 2f6a /* 0x00fe */ 325d /* 0x00ff */ % 7.2.9 dump imem This command generates a text file representing the contents of the specified address range of internal or external instruction memory. The user specifies internal or external memory, the starting address, and the size of the region to dump. Format dump imem {int|ext} filename addr size Example zisim{32} dump imem int imem.dat 0x1000 0x30 % cat imem.dat 0000 /* 0x1000 0000 /* 0x1001 0000 /* 0x1002 0000 /* 0x1003 ... 0000 /* 0x102c 0000 /* 0x102d 0000 /* 0x102e 0000 /* 0x102f % */ */ */ */ */ */ */ */ 7-10 ZISIM Simulator 7.2.10 enable break This command enables a breakpoint from the current list of defined breakpoints. Use the show break command to display a list of current breakpoints. Format enable break breakpoint_number Example zisim{32} enable break 1 7.2.11 enable trace This command enables a predefined trace type. There are three types of predefined run-time tracing. Run-time traces generate text output instruction by instruction. The three trace types are: * mem Displays address and data for any memory location which is updated. Information is generated after the instruction is executed. * * reg Displays all registers and register values every instruction. write Displays architectural state changes associated with memory or registers for each instruction. Format enable trace {mem|reg|write} Example zisim{32} enable trace write 7.2.12 exit This command terminates the current simulation session. Format exit ZISIM Commands 7-11 7.2.13 fill dmem This command fills internal or external data memory range with specified value. User specifies internal or external memory, the starting address, and the size of the region to fill. Format fill dmem {int|ext} addr size value Example zisim{32} fill dmem ext 0x1000 0xff 0x0505 7.2.14 fill imem This command allows you to specify internal or external memory, the starting address, and the size of the region to fill. Format fill imem {int|ext} addr size value Example zisim{32} fill imem ext 0x1000 0xff 0x0505 7.2.15 help This command displays help information. Help is available for individual commands as well as for command categories. Specifying a command displays the description and usage for that command. Requesting help for a specified category displays the instructions associated with that category. Commands are categorized according to their function (for instance, all show commands). Issuing the help command with no other specifiers displays help on the command categories. Format help [category|command] Examples zisim{32} help 7-12 ZISIM Simulator zisim{32} help all zisim{32} help show zisim{32} help show reg 7.2.16 load dmem This command loads internal or external data memory from specified text file. User specifies internal or external memory, the starting address, and the size of the region to load. The format of the text file should be the same as the file produced by the dump command. The first column contains the data that will be loaded, with each data on a single line. Data must be in hex format with out 0x prefix. Comments must be enclosed by `/* */ '. Format load dmem {int|ext} filename addr size Example zisim{32} load dmem int data.dat 0x1000 0x0fff The output format of the file is: %cat data.dat 2ce5 /* 0x0000 3c3f /* 0x0001 2000 /* 0x0002 3006 /* 0x0003 a00f /* 0x0004 80c0 /* 0x0005 ... */ */ */ */ */ */ 7.2.17 load exe This command loads a valid ZSP executable into instruction memory. This command performs the same function as specifying the executable filename when ZISIM is invoked. Without the filename specified, this command reloads the previous executable program into memory. Format load exe {filename} ZISIM Commands 7-13 Example zisim{32} load exe test.exe or zisim{32} load test.exe 7.2.18 load imem This command loads internal or external instruction memory from specified text file. You must specify internal or external memory, the starting address, and the size of the region to load. You must ensure that the format of the text file is the same as the file produced by the dump command. The first column contains the data that will be loaded, with each data on a single line. Data must be in hex format without the 0x prefix. Comments must be enclosed by `/* */ '. Format load imem {int|ext} filename addr size Example % cat inst.txt 2ce5 /* 0x0000 3c3f /* 0x0001 2000 /* 0x0002 3006 /* 0x0003 a00f /* 0x0004 80c0 /* 0x0005 bc4c /* 0x0006 6f4c /* 0x0007 */ */ */ */ */ */ */ */ zisim{32} load imem int inst.txt 0x1000 8 7.2.19 reset This command resets the state of the simulator. A soft reset initializes all aspects of the simulator except the memory. A hard reset also initializes memories. Issuing the reset command without options performs a soft reset. Format reset [soft|hard] 7-14 ZISIM Simulator Examples zisim{32} reset soft zisim{32} reset hard Note that the reset command does not reload the program into memory. In order to restart the program, perform one of the following sequence of commands: zisim{32} reset zisim{32} set reg pc 7.2.20 run This command advances the simulator the specified number of instructions. The simulator uses the value of the run attribute if no instruction count is specified. Simulation halts if instruction count is reached, the maximum instruction count is reached, or a system halt occurs. Format run [number_of_instructions] Examples zisim{32} run zisim{32} run 100 7.2.21 script This command loads and processes the script file. Script files may contain any valid ZISIM commands. Comments are allowed in the script file; the comment specifier is the # character. ZISIM ignores all commands between the # character and the end of line. Empty lines are also ignored. Format ZISIM Commands 7-15 script filename Example zisim{32} script standard.scr Sample Script File A simple script is shown below. # This example script demonstrates how to turn on # instruction tracing using a command. load test.exe enable trace write run exit 7.2.22 set attr The set attr command allows you to set three internal ZISIM variables. Table 7.5 shows the configurable ZISIM attributes. Table 7.5 Attribute history radix run Configurable ZISIM Attributes Value any integer [int | hex] any integer Description Number of commands to maintain in history buffer. Radix (integer or hexadecimal) used to generate output. Default instruction count for the run command (when issuing the run command with no argument). If undefined, the default value of the run attribute is 2000000000. Format set attr [history|radix|run] value Examples zisim{32} set attr run 1000 zisim{32} set attr radix hex 7-16 ZISIM Simulator 7.2.23 set break This command creates and enables a new breakpoint at specified address. Execution halts when the PC reaches the specified address. When a new breakpoint is created, ZISIM tags it with a breakpoint number which is used for other breakpoint commands (use the show break command to view a list of current breakpoints). Format set break pc addr set break symbol label Example zisim{2} set Breakpoint 1 zisim{3} set Breakpoint 2 break on PC break on PC pc 0x0010 at address 0x0010 symbol main at address 0xf9b9 of main 7.2.24 set reg This command assigns a value to the specified register. Format set reg register value Example zisim{32} set reg r0 0x1234 7.2.25 set size 7.2.25.1 zisim400 This command sets the size of internal data memory or instruction memory. The default size of internal data or instruction memory is 63488 words (62K words), which is also the maximum size that can be set. This command does not apply to external memory. (The simulator has 1M words for each external instruction and external data memory.) Format set size {dmem|imem} size ZISIM Commands 7-17 Examples zisim{32} set size dmem 0x4000 This command sets the size of internal data memory to 16 Kwords. zisim{32} set size imem 0x4000 This command sets the size of internal instruction memory to 16 Kwords 7.2.25.2 zisimg2 This command sets the size of internal/external data memory or instruction memory. The default size of internal/external data or instruction memory is 0xffffffwords (16M words) starting from 0, which is also the maximum size that can be set. This command does not apply to external memory. (The simulator has 1M words for each external instruction and external data memory.) Format set size {dmem|imem} {int|ext} beg_value end_value Examples zisim{32} set size dmem int 0 0xffff This command sets the size of internal data memory to 16 Kwords. zisim{32} set size imem int 0 0xffff This command sets the size of internal instruction memory to 16 Kwords. . 7.2.26 show attr This command shows the value of the specified attribute. You can view the value of the three attributes which are configurable with the set attr command as well as view version information for ZISIM. Format show attr {run|history|radix|version} Example 7-18 ZISIM Simulator zisim{1} zisim{2} zisim{3} zisim{4} show show show show attr attr attr attr run history radix version 7.2.27 show bits This command displays the bit field values for the specified register. Do not use the % specifier for control registers. Format show bits register Example zisim{32} show bits hwflag hwflag = 0x0000 er: 0 ex: 0 ir: 0 z: 0 gt: 0 ge: 0 c: 0 gsv: 0 sv: 0 gv: 0 v: 0 7.2.28 show break This command displays the list of currently defined breakpoints. Format show break Example zisim{32} show break Num ID Address Status ----------------------2 PC 0x2000 Active 1 PC 0xf9b9 Active ZISIM Commands 7-19 7.2.29 show dmem This command displays a range of internal or external data memory. You must specify internal or external memory, the starting address, and the size of the region to display. The default settings for the show dmem command are shown in Table 7.6. Table 7.6 Argument {int | ext} addr size Default Arguments for show dmem Value int 0x0 16 Format show dmem {int|ext} addr size Example zisim{32} show dmem int 0xf000 0x10 For zisimg2, user can use a symbol instead of an absolute address value. zisim{1} show dmem int array1 20 7.2.30 show imem This command displays a range of internal or external instruction memory. User specifies internal or external memory, the starting address, and the size of the region to show. The size and addr fields may be omitted, in which case defaults are used. The default settings for the show imem command are shown in Table 7.7. Table 7.7 Argument {int | ext} addr size Default Arguments for show imem Value int 0x0 16 7-20 ZISIM Simulator Format show imem {int|ext} [addr] [size] Example zisim{32} show imem int 0xf000 0x10 For zisimg2, user can use a symbol instead of an absolute address value. zisim{1} show imem int foo_function 20 7.2.31 show reg This command displays the value of a specified register or the value of a category of registers. More than one category and/or register can be specified. The register categories are: * * gpr All general purpose registers, r0-r15. cfg All control registers (such as %smode and %hwflag). Do not include the percent sign (%) in the register name. * addr All address and index registers for the ZSPG2 architecture. Thus, it is specific for zisimg2. Format show reg {category|register} ... Examples zisim{32} zisim{32} zisim{32} zisim{32} show show show show reg gpr cfg r0 gpr hwflag smode ZISIM Commands 7-21 7.2.32 show size 7.2.32.1 zisim400 This command shows the size of internal data or instruction memory. The output is not affected by the radix attribute. Format show size {dmem|imem} Examples zisim{32} show size dmem zisim{32} show size imem 7.2.32.2 zisimg2 This command shows the size of internal/external data or instruction memory. The output is not affected by the radix attribute. Format show size {dmem|imem}{int|ext} Examples zisim{32} show size dmem int zisim{32} show size imem int 7.2.33 show stats This command displays run-time statistics collected by ZISIM. If no argument is specified, ZISIM displays overall statistical information. If the opcode argument is specified, ZISIM displays instruction opcode statistics. Format show stats [opcode] Examples zisim{32} show stats zisim{32} show stats opcode 7-22 ZISIM Simulator 7.2.34 show trace This command shows currently enabled/disabled trace information. Traces currently set to ON are enabled during simulation. Format show trace Example zisim{32} show trace ***(info) Supported trace information: - Instruction trace: OFF - Register trace: OFF - Memory trace: OFF zisim{33}> enable trace write ***(info) Instruction trace is ON. zisim{34}> show trace ***(info) Supported trace information: - Instruction trace: ON - Register trace: OFF - Memory trace: OFF 7.2.35 step This command single-steps the simulator. Issuing the step command is equivalent to issuing the command run 1. Format step Example zisim{32} step 7.2.36 unalias This command deletes an alias. (Use the alias command to display a list of currently defined aliases.) Format unalias alias Example ZISIM Commands 7-23 zisim{32} unalias adv 7.3 I/O Port Usage ZISIM400 models serial I/O as a memory-mapped device. Programs perform terminal I/O by reading from and writing to the appropriate address locations. The simulator defines two serial ports and one host processor interface (HPI) port. Each port has a transmit buffer and a receive buffer. Table 7.8 shows the memory addresses and corresponding files for the I/O ports for the LSI402ZX, LSI403Z, and ZSP400-core based devices. Table 7.8 I/O Device Memory Map and Associated Files Read I/O Port Serial Port 0 Serial Port 1 Host Interface Port Address 0xF901 0xFA01 0xFB01 File sp0in sp1in hpiin Address 0xF900 0xFA00 0xFB00 Write File sp0out sp1out hpiout The format of input and output files is the same. Data must be in decimal digits, with each data on a single line. If the input file is not present in the current running directory at the time of the request, the simulator will print an error message to standard output and exit. 7.4 Example Session Using ZISIM This section contains an example simulation session using ZISIM in interactive mode. In the example simulation, demo.exe is invoked using the -t (enable trace) command-line option. Trace information is displayed in five fields: (0) 0x2000 2cfb movl r12, 0xfb ! r12 = 0x00fb * The first field is the instruction sequence number (in parenthesis). 7-24 ZISIM Simulator * * * * The second field is the program counter (PC) of the executed instruction. The third field is the instruction opcode. The fourth field is the disassembled instruction, including operands. The fifth field describes the result of the executed instruction. The trace shown in this example is for the ZSP400 core. The text is linked and loaded at 0x2000. Example Session Using ZISIM 7-25 (shell prompt) zisim400 demo.exe -t ************************************************* ZISIM 1.206 ZSP400 Instruction Set Simulator LSI Logic ************************************************* ***(info) Starting address: 0x2000 .text : Loading to INT-INST memory ... 0x2000 -> 0x2950 (0x0951) .data : Loading to INT-DATA memory ... 0x0001 -> 0x005f (0x005f) Loading "demo.exe" successfully. zisim{1}_ If you do not specify a test for initialization, you can load a test from the ZISIM command line. Check the contents of the instruction memory to confirm proper loading of the test. These steps are demonstrated below. zisim{1}show imem int 0x2000 4 0x2000 0x2cfb movl r12, 0xfb 0x2001 0x3cf7 movh r12, 0xf7 0x2002 0xa6d0 mov r13, 0x0 0x2003 0x2460 movl r4, 0x60 zisim{2}> _ Instruction fetch begins at the entry point you specify in an executable program. You can change this before execution begins by setting the PC to the desired value using the set reg command. The simulator output below demonstrates use of the PC breakpoint: a breakpoint is set for address 0x10 and the simulator advances until the PC reaches address 0x10. 7-26 ZISIM Simulator zisim{3}> set break pc 0x2050 Breakpoint 1 on PC at address 0x2050 zisim{4}> set break symbol main Breakpoint 2 on PC at address 0x2010 of main zisim{5}> run (0) 0x2000 2cfb movl r12, 0xfb ! r12 = 0x00fb (1) 0x2001 3cf7 movh r12, 0xf7 ! r12 = 0xf7fb (2) 0x2002 a6d0 mov r13, 0x0 ! r13 = 0x0000 (3) 0x2003 2460 movl r4, 0x60 ! r4 = 0x0060 (4) 0x2004 3400 movh r4, 0x0 ! r4 = 0x0060 (5) 0x2005 bc54 mov r5, r4 ! r5 = 0x0060 (6) 0x2006 a051 add r5, 0x1 ! hwflag = 0x0030 (6) 0x2006 a051 add r5, 0x1 ! r5 = 0x0061 (7) 0x2007 6054 st r5, r4, 0 ! INT-DATA[0x0060] = 0x0061 (8) 0x2008 bb1d mov rpc, r13 ! rpc = 0x0000 (9) 0x2009 2510 movl r5, 0x10 ! r5 = 0x0010 (10) 0x200a 3520 movh r5, 0x20 ! r5 = 0x2010 (12) 0x200c a750 call r5 ! rpc = 0x200d (PC BREAKPOINT #2)................ Instruction Count=000013 PC=0x2010 zisim{6}> show reg gpr r0 = 0x0000 r1 = 0x0000 r2 = 0x0000 r3 = 0x0000 r4 = 0x0060 r5 = 0x2010 r6 = 0x0000 r7 = 0x0000 r8 = 0x0000 r9 = 0x0000 r10 = 0x0000 r11 = 0x0000 r12 = 0xf7fb r13 = 0x0000 r14 = 0x0000 r15 = 0x0000 zisim{7}> disable trace write After the final command, the simulator will no longer print the instruction flow trace. zisim{8}> run Hello World! (SYSTEM HALT)..................... Instruction Count=000673 PC=0x200e Execution halts when a breakpoint is reached, a system halt occurs, or the maximum instruction count is reached. A system halt refers to setting halt mode as defined by the %smode control register. Execution statistic information can be seen by using show stats command. zisim{9}> 673 88 65 23 56 37 19 show stats instructions executed load instructions ( 13.08%) - single ( 9.66%) - double ( 3.42%) store instructions ( 8.32%) - single ( 5.50%) - double ( 2.82%) Example Session Using ZISIM 7-27 104 15 63 10 25 discontinuities - calls - conditional - agnx mispredicts ( 15.45%) ( 2.23%) ( 9.36%) ( 1.49%) ( 39.68% of conditional branch) Terminate the simulation session with the exit command. zisim{10}> exit ***(info) Exiting ZISIM. 7-28 ZISIM Simulator Chapter 8 ZSIM Simulator This chapter describes the ZSP SDK cycle-accurate architecture simulator. The ZSP SDK simulator ZSIM is a cycle-accurate simulator for ZSP400 and ZSPG2 architecture-based devices. ZSIM models the architectural features necessary for cycle-by-cycle tracing of architectural state, including the execution pipeline, instruction and data caches, internal and external instruction/data memories, and register files. 8.1 Using ZSIM ZSIM can be accessed as a target through the debugger or as a standalone program. This chapter describes the interface to ZSIM as a standalone program. ZSIM can be used in batch mode or interactively, as described in the following subsections. The commands supported in both modes of operation are described in Section 8.2, "ZSIM Commands," page 8-5. 8.1.1 Batch Mode The simulator can be invoked in batch mode from the command line using the -exec option, as shown below. % zsim[400/g2] executeable_file -exec [options] The simulator can also be invoked in batch mode using a script file containing ZSIM commands that load, execute, and gather results for a specified executable. Script files may contain any valid ZSIM commands. Comments are allowed and must be preceded by the comment specifier (#). ZSIM ignores all commands between the # character and the end of line. ZSIM also ignores empty lines. ZSP SDK Software Development Kit 8-1 A simple script file that turns on instruction tracing and then executes the program test.exe is shown below. load test.exe enable trace write run 100000 exit Assuming the file batch.scr contains the commands shown above, a trace file for test.exe could be generated as follows: % zsim400 -s batch.scr > test.trace (Unix for ZSP400 architecture) % zsimg2 -s batch.scr > test.trace (Unix for ZSPG2 architecture) C:\zsim400 -s batch.scr > test.trace (Windows for ZSP400 architecture) C:\zsimg2 -s batch.scr > test.trace (Windows for ZSPG2 architecture) Refer also to Section 8.2.26, "script," page 8-21. 8.1.2 Interactive Mode In interactive mode, ZSIM is invoked from the command line using the following command: For ZSP400 architecture: zsim400 [executable_file] [options] For ZSPG2 architecture: zsimg2 [executeable_file] [options] You may optionally specify an executable file, followed by zero or more command-line options, which must be separated by spaces The executable file is a ZSP binary file generated using the SDK compiler, assembler, and linker tools, as explained in other chapters of this document. ZSIM processes the source file according to the specified command-line options (refer to Table 8.1). If no options are specified, ZSIM initializes itself, then prompts the user with the ZSIM prompt: 8-2 ZSIM Simulator zsim{1}> The simulator is now ready to accept and respond to ZSIM commands, which are described in Section 8.2, "ZSIM Commands" on page 8-5. An executable file may be loaded from within ZSIM using the load exe command. An example interactive simulation session is described in Section 8.4, "Example Session Using ZSIM" on page 8-34. Refer also to the description of using ZSIM use as the target of the SDK's Debugger in Section 9.2.2, "Cycle-Accurate Simulator Connection," page 9-4. Table 8.1 Option -exec -c num -h ZSIM Command-line Options Description Invokes the simulator in noninteractive mode. Specifies maximum cycle count. Execution aborted after num cycles. Prints brief usage summary. -i mode_register=value Initializes an architectural control (mode) register with specified value. The control register is written without its usual percent (%) sign, and there are no spaces around the equal sign (=). For example, the option to set %smode control register is: -i smode=0x1234. The option to set r0 register is -i r0=0x9876. Refer to Appendix B, "ZSP400 Control Registers" for information on ZSP400 core-based device control registers or Appendix D"ZSPG2 Control Registers" -m -p -pf -pfiu -pfpipe (Sheet 1 of 2) Turns on memory trace. Turns on pipeline trace. Turns on all profile information. Turns on instruction unit profile information. Turns on pipeline unit profile information. Using ZSIM 8-3 Table 8.1 Option -q ZSIM Command-line Options (Cont.) Description Suppresses startup banner. Displays data in the specified radix, either decimal (dec) or hexadecimal (hex). Turns on register trace. Executes the specified script file following initialization. Turns on instruction trace. Prints ZSIM version number. -radix {dec | hex} -reg -s sourcefile -t -v (Sheet 2 of 2) Table 8.2 Options -wed num -wei num -sid num -sii num -mempcr num -nomempcr -noiboot Command-line Options for zsim400 Description Sets EXT-DATA memory wait state to be num. Default is 1. Sets EXT-INST memory wait state to be num. Default is 1. Sets INT-DATA memory size to be num. Default is 63488 words. Sets INT-INST memory size to be num. Default is 63488 words. Sets the MEMPCR address to be num. Default is 0xf807. Indicates that the system does not have MEMPCR. Sets the IBOOT signal LOW to boot from external ROM. If this option is not specified, instructions are fetched from internal ROM space. ROM is mapped from 0xf800 to 0xffff. Turns on data unit profile information. -pfdu 8-4 ZSIM Simulator Table 8.3 Options -pflsu -tic Command-line Options for zsimg2 Description Turn on Load Store Unit profile information Turn on instruction cache trace every cycle Set system vector table address to be ADDR Use ideal memory subsystem with zero delay for internal memory and no checking for banking conflict between 2 data access ports. Use bus interface library LIBNAME to run in co-simulation enviroment such as SWIFT or CVE Seamless. Use co-processor library LIBNAME. SDK tools comes with an example G711 coprocessor library called libzcpig711.so on Solaris or libzcpig711.dll on Windows platform. -svtadd ADDR -idealmss -bimlib LIBNAME -cpilib LIBNAME 8.2 ZSIM Commands The ZSIM commands are described briefly in Table 8.4 and in detail in the following subsections. The output of any ZSIM command can be sent to a file using the standard redirection identifier (>). For example, the command show attr > mydisplay writes the output of the show command in the file mydisplay. Table 8.4 Command alias ZSIM Command Summary Modifier Argument - [tag command_sequence] Description Creates alias (tag) for command sequence. (Sheet 1 of 4) ZSIM Commands 8-5 Table 8.4 Command clear ZSIM Command Summary (Cont.) Modifier Argument break dmem icache imem stats breakpoint_number {int | ext} addr size - {int | ext} addr size - breakpoint_number [du | iu | pipe] {pipe | reg} Description Clears specified breakpoint. Clears internal or external data memory. Clears instruction cache. Clears internal or external instruction memory. Clears statistic information. Disables specified breakpoint. Disables profile information. Disables run-time tracing. disable break profile trace dump dmem imem {int | ext} filename addr size Dumps internal or external data memory to a text file filename. {int | ext} filename addr size Dumps internal or external instruction memory to a text file filename. breakpoint_number {iu | pipe} Enables breakpoint. Enables module profile information. enable break profile trace {mem | pipe | reg | write| icache} Enables run-time cycle tracing. - {int | ext} addr size value {int | ext} addr size value {category | command} Exits simulation session. Fills internal/external data memory segment with value. Fills internal/external instruction memory segment with value. Prints list of commands in a category or command usage. Advances the simulator by one instruction. exit fill - dmem imem help istep - - (Sheet 2 of 4) 8-6 ZSIM Simulator Table 8.4 Command load ZSIM Command Summary (Cont.) Modifier Argument dmem exe imem {int | ext} filename addr filename {int | ext} filename addr {hard | soft} [number_of_cycles] filename {history | radix | run} value pc addr symbol label register value Description Loads internal/external data memory from file. Loads ZSP executable into instruction memory. Loads internal/external instruction memory from file. Reset simulator (hard or soft). Runs for specified number of simulation cycles. Loads and executes ZSIM script file. Assigns value to specified attribute. Creates a new breakpoint at the specified PC address. Creates a new breakpoint at the specified label. Assigns value to specified register. reset run script set hard - - attr break break reg (Sheet 3 of 4) ZSIM Commands 8-7 Table 8.4 Command show ZSIM Command Summary (Cont.) Modifier Argument attr bits break dmem icache imem pipe profile reg rule size stats trace {history | radix | run | version} register - { int | ext} addr size - {int | ext} addr size - - {category | reg}... - {dmem | imem} - - - alias Description Shows value of the specified attribute. Displays the bit-level states for the specified register. Shows list of defined breakpoints. Shows contents of a region of internal/external data memory. Shows current instruction cache contents. Shows contents of a region of internal/external instruction memory. Shows contents and state of execution pipeline. Displays supported profile information. Shows contents of register or register set. Shows the affected grouping rule in the current cycle. Shows size of internal data or instruction memory. Shows current run-time statistics. Shows the current status of all tracing attributes. Advances simulation by one cycle. Same as run 1. Deletes alias. step unalias - - (Sheet 4 of 4) 8-8 ZSIM Simulator Table 8.5 Command clear set ZSIM400 specific commands Modifier dcache delay Argument [edata|einst] num Description Clear data cache. Sets wait state for external memory. Default for both external data and instruction memory is 1. Set internal instruction or internal data memory size starting from 0. Default size is maximum value of 0xf800 words. Show size of internal instruction or data memory Show data cache contents. Enable profile information on Data Unit. Disable profile information on Data Unit. set size [dmem|imem] size show show enable disable size dcache profile profile [dmem|imem] du du ZSIM Commands 8-9 Table 8.6 Command set ZSIMG2 specific commands Modifier latency Argument [dmem|imem] [int|ext] num Description Set wait state latency for internal/external instruction or data memory. Default value for internal memory is 2 and external memory is 5. Show wait state latency for internal/external instruction or data memory. Set the size of internal/external instruction or data memory starting from beg_value to end_value including the boundary. Each memory block could overlap one another. Default value for each of them is from 0 to 0x00ffffff words. Show the current size of internal/external instruction or data memory. Show operand values of an instruction number. Instruction number can be obtained by looking at the output of "show pipe" command. Display the statistic of grouping rule. Turn on profile information of Load Store Unit. Turn off profile information of Load Store Unit. show latency [dmem|imem] [int|ext] set size [dmem|imem] [int|ext] beg_value end_value show size [dmem|imem] [int|ext] show operands instruction_number show enable disable stats profile profile grouping lsu lsu 8-10 ZSIM Simulator 8.2.1 alias This command creates an alias for a ZSIM command. This command allows you to customize the ZSIM commands by aliasing new commands to existing commands or sequences of commands. Sequences of commands must be contained in quotes and separated by semicolons. Issuing the alias command without arguments displays all current aliases. Format alias [tag] [command_sequence] Examples zsim{32} alias r0 show reg r0 zsim{32} alias adv "step ; show pipe ; show reg gpr" zsim{32} alias adv step ; show pipe ; show reg gpr r0 show reg r0 zsim{33} 8.2.2 clear break This command deletes a breakpoint from the current list of defined breakpoints. The breakpoint number is assigned when a breakpoint is set. Use the show break command to display a list of breakpoints. Format clear break breakpoint_number Example zsim{32} clear break 5 8.2.3 clear dcache This command invalidates the contents of the data cache. Format clear dcache ZSIM Commands 8-11 Example zsim{32} clear dcache 8.2.4 clear dmem This command clears the contents of internal or external data memory. User specifies internal or external memory, the starting address, and the size of the region to clear. Format clear dmem {int|ext} addr size Example zsim{32} clear dmem int 0x1000 0x0100 8.2.5 clear icache This command clears the contents of the instruction cache. Format clear icache Example zsim{32} clear icache 8.2.6 clear imem This command clears the contents of internal or external instruction memory. User specifies internal or external memory, the starting address, and the size of the region to clear. Format clear imem {int|ext} addr size Example zsim{32} clear imem ext 0x7000 0x1000 8-12 ZSIM Simulator 8.2.7 clear stats This command clears all the run-time statistical information, which includes the cycle count, the number of executed instructions, and the number of instructions that are being grouped in the pipe. Format clear stats Example zsim{32} clear stats 8.2.8 disable break This command disables a breakpoint from the current list of active breakpoints. (Use the show break command to display current list.) Format disable break breakpoint_number Example zsim{32} disable break 4 8.2.9 disable profile This command disables specified type of profile information. If no profile type is specified, the command will disable all types. Profile types are described in Section 8.2.14, "enable profile," page 8-15. Format disable profile [du|iu|pipe] Examples zsim{32} zsim{32} zsim{32} zsim{32} disable disable disable disable profile du profile iu profile pipe profile ZSIM Commands 8-13 8.2.10 disable trace This command disables specified type of trace. Trace types are described in Section 8.2.15, "enable trace," page 8-16. Format disable trace type Examples zsim{32} disable trace pipe zsim{32} disable trace reg 8.2.11 dump dmem This command generates a text file representing the contents of the specified address range of the internal or external data memory. The user specifies internal or external memory, the starting address, and the size of the region to dump. Format dump dmem {int|ext} filename addr size Example zsim{32} dump dmem ext data.dat 0x0000 0x100 % cat data.dat 0000 /* 0x0000 0000 /* 0x0001 0000 /* 0x0002 0000 /* 0x0003 0000 /* 0x0004 0000 /* 0x0005 0000 /* 0x0006 ... 28e2 /* 0x00fd 2f6a /* 0x00fe 325d /* 0x00ff % */ */ */ */ */ */ */ */ */ */ 8.2.12 dump imem This command generates a text file representing the contents of the specified address range of the internal or external instruction memory. 8-14 ZSIM Simulator The user specifies internal or external memory, the starting address, and the size of the region to dump. Format dump imem {int|ext} filename addr size Example zsim{32} dump imem int imem.dat 0x1000 0x30 % cat imem.dat 0000 /* 0x1000 0000 /* 0x1001 0000 /* 0x1002 0000 /* 0x1003 ... 0000 /* 0x102c 0000 /* 0x102d 0000 /* 0x102e 0000 /* 0x102f % */ */ */ */ */ */ */ */ 8.2.13 enable break This command enables a breakpoint from the current list of defined breakpoints. See Section 8.2.28, "set break," page 8-23, for a description of how to create a breakpoint. Format enable break breakpoint_number Example zsim{32} enable break 1 8.2.14 enable profile This command enables a predefined trace type. Run-time traces generate text output representing the state of the architecture on a cycleby-cycle basis. There are three types of predefined run-time tracing: * du Displays information from the data unit of the ZSP400 architecture, such as data cache hits and the du_imem_read signal. ZSIM Commands 8-15 * iu Displays information from the instruction unit, such as instruction cache hits and the iu_imem_read signal. * pipe Displays information from the pipeline unit, such as cycle-by-cycle grouping rule information. * lsu Displays information from the load/store unit of ZSPG2 architecture.. Format enable profile {du|iu|pipe|lsu} Examples zsim{1} enable profile du ***(info) Data Unit profile information is ON. zsim{2} enable profile iu ***(info) Instruction Unit profile information is ON. zsim{3} enable profile pipe ***(info) Pipeline Unit profile information is ON. 8.2.15 enable trace This command enables a predefined trace type. Run-time traces generate text output representing the state of the architecture on a cycleby-cycle basis. There are four types of predefined run-time tracing: * mem Displays address and data for any memory location which is updated. Information is generated in the cycle in which the write occurs. * * * pipe Displays the entire pipeline in every cycle. reg Displays all registers and values in every cycle. write 8-16 ZSIM Simulator Displays architectural state changes associated with memory or registers for each cycle. Format enable trace {mem|pipe|reg|write} Example zsim{32} enable trace write 8.2.16 exit This command terminates the current simulation session. Format exit Example zsim{32} exit 8.2.17 fill dmem This command fills internal or external data memory range with specified value. Format fill dmem {int|ext} addr size value Example zsim{32} fill dmem ext 0x1000 0xff 0x0505 8.2.18 fill imem This command fills internal or external instruction memory range with specified value. Format fill imem {int|ext} addr size value Example zsim{32} fill imem ext 0x1000 0xff 0x0505 ZSIM Commands 8-17 8.2.19 help This command displays help information about commands. Commands are categorized according to their function. Requesting help without specifiers displays help on the command categories; requesting help for a specified category displays the instructions associated with that category. Specifying a particular command displays the description and usage for that command. Format help [category|command] Examples zsim{32} zsim{32} zsim{32} zsim{32} help help all help show help show reg 8.2.20 istep This command steps the program instruction by instruction. By default, this command is aliased to is. For zsimg2, user can specify a number to indicate number of instructions to be executed. Format istep or is Examples zsim{22}> istep CYCLE=000012 PC=0x200c 0x2008 mov rpc, r13 zsim{23}> is CYCLE=000012 PC=0x200c 0x2009 movl r5, 0x10 zsim{24}> CYCLE=000013 PC=0x200c 0x200a movh r5, 0x20 8-18 ZSIM Simulator zsim{25}> CYCLE=000013 PC=0x200c 0x200b nop zsim{26}> CYCLE=000015 PC=0x200d 0x200c call r5 zsim{27}> CYCLE=000020 PC=0x2014 0x2010 mov r13, rpc 8.2.21 load dmem This command loads internal or external data memory from the specified text file. You must specify internal or external memory, the starting address, and the size of the region to load. You must ensure that the format of the text file is the same as the file produced by the dump command. The first column contains the data that will be loaded, with each data on a single line. Data must be in hex format without the 0x prefix. Comments must be enclosed by `/* */ '. Format load dmem {int|ext} filename addr size Example zsim{32} load dmem int data.dat 0x1000 20 The output format of the file is: %cat data.dat 2ce5 /* 0x0000 3c3f /* 0x0001 2000 /* 0x0002 3006 /* 0x0003 a00f /* 0x0004 80c0 /* 0x0005 ... */ */ */ */ */ */ 8.2.22 load exe This command loads a valid ZSP executable into instruction memory. This command performs the same function as specifying the executable filename when ZSIM is invoked. Format ZSIM Commands 8-19 load exe filename Example zsim{32} load exe test.exe or zisim{32} load test.exe 8.2.23 load imem This command loads internal or external instruction memory from specified text file. You must specify internal or external memory, the starting address, and the size of the region to load. You must ensure that the format of the text file is the same as the file produced by the dump command. The first column contains the data that will be loaded, with each data on a single line. Data must be in hex format without the 0x prefix. Comments must be enclosed by `/* */ '. Format load imem {int|ext} filename addr size Example % cat inst.txt 2ce5 /* 0x0000 3c3f /* 0x0001 2000 /* 0x0002 3006 /* 0x0003 a00f /* 0x0004 80c0 /* 0x0005 bc4c /* 0x0006 6f4c /* 0x0007 */ */ */ */ */ */ */ */ zsim{32} load imem int imem.txt 0x1000 8 8.2.24 reset This command resets the state of the simulator. The default is a soft reset, which initializes all aspects of the simulator except the instruction memory. A hard reset performs full initialization. Format 8-20 ZSIM Simulator reset [soft|hard] Examples zsim{32} reset zsim{32} reset hard Important: The reset command does not reload the program into memory. In order to restart the program, perform one of the following sequence of commands: zsim{32} reset zsim{32} set reg pc 8.2.25 run This command advances the simulator for the specified number of cycles. If no cycle count is specified, the default cycle count defined for the run attribute is used (refer to Section 8.2.27, "set attr," page 8-22). Simulation halts if cycle count is reached, the maximum cycle count is reached, or a system halt occurs. Format run [number_of_cycles] Examples zsim{32} run zsim{32} run 100 8.2.26 script This command loads and processes script file. The script file may contain any valid ZSIM commands. Comments are allowed in the script file, preceded by the hash (#) character. ZSIM ignores all commands between the # character and the end of line. Empty lines are also ignored. Format ZSIM Commands 8-21 script filename Example zsim{32} script standard.scr Example Script File # This example script demonstrates how to turn on # instruction and pipeline tracing using a command. load test.exe enable trace write enable trace pipe run exit 8.2.27 set attr The set attr command allows you to set three internal ZSIM attributes. These configurable attributes are shown in Table 8.7. Table 8.7 Attribute history radix run Configurable ZSIM Attributes Value any integer {dec | hex} any integer Description Number of commands to maintain in history buffer. Radix (decimal or hexadecimal) used to generate output. Default cycle count for the run command (when issuing the run command with no argument). If undefined by the set attr command, the default run value is 100000 cycles. Format set attr attribute value Examples zsim{32} set attr run 1000 zsim{32} set attr radix hex 8-22 ZSIM Simulator 8.2.28 set break This command creates and enables a new breakpoint at specified address. Breakpoints can be set for the program counter. Execution halts at the cycle when the instruction at the specified address is in the set of instructions which are about to be executed in the pipeline's E stage. When a new breakpoint is created, it is tagged with a breakpoint number which is used by other breakpoint commands. Use the show break command to display a list of current breakpoints. Format set break pc addr set break symbol label Example zsim{1} set break pc 0x0010 Breakpoint 1 on PC at address 0x0010 zsim{2} set break symbol main Breakpoint 2 on PC at address 0xf9b9 of main 8.2.29 set delay This command sets the delay wait state of external data memory or instruction memory. The default delay value is 1 for both external data and instruction memory. The wait state is the number of cycles between requesting data and having it returned. For example, wait state equals 1 means that data is returned 1 cycle after it is requested. Format set delay {edata | einst} num Example zsim{1} set delay edata 10 zsim{2} set delay einst 20 Note: This command is specific to zsim400 ZSIM Commands 8-23 8.2.30 set latency This command sets the delay wait state of internal/external data memory or instruction memory. The default delay value is 2 for both internal data and instruction memory. The default delay value is 5 for both external data and instruction memory. The wait state is the number of cycles between requesting data and having it returned. For example, wait state equals 2 means that data is returned 2cycles after it is requested. Format set latency {imem | dmem} {int | ext} num Example zsim{1} set latency dmem int 10 zsim{2} set latency dmem ext 20 Note: This command is specific to zsimg2 8.2.31 set reg This command assigns a new value to the specified register. Format set reg register value Example zsim{32} set reg r0 0x1234 8.2.32 set size 8.2.32.1 zsim400 This command sets the size of internal data memory or instruction memory. The default size of internal data or instruction memory is 63488 words (62K words), which is also the maximum size that can be set. 8-24 ZSIM Simulator Important: This command does not apply to external memory. (The simulator has 1M words for each external instruction and external data memory.) Format set size {dmem|imem} size Examples zsim{1} set size dmem 0x4000 zsim{2} set size imem 0x3000 8.2.32.2 zsimg2 This command sets the size of internal/external instruction or data memory from a begin value to an end value. The boundary is inclusive. The default size for each of the 4 memory types is the maximum value from 0 to 0x00ffffff words (16M words). A word is a 16-bit value for the ZSPG2 architecture. Format set size {dmem|imem} {int|ext} beg_value end_value Examples zsim{1} zsim{2} zsim{3} zsim{4} set set set set size size size size dmem imem dmem imem int int ext ext 0 0 0 0 0xffff 0xffff 0x00fffff 0x00fffff 8.2.33 show attr This command displays the value of the specified attribute. See set attr for a list of defined attributes. Note that the version attribute can only be used with the show attr command; it cannot be used with the set attr command. Format show attr {history|radix|run|version} Example ZSIM Commands 8-25 zsim{32} show attr run 8.2.34 show bits This command displays the bit field values for the specified register. When specifying control registers, do not include the percent (%) sign. Format show bits register Example zsim{32} show bits hwflag hwflag = 0x0000 er: 0 ex: 0 ir: 0 z: 0 gt: 0 ge: 0 c: 0 gsv: 0 sv: 0 gv: 0 v: 0 8.2.35 show break This command displays the list of currently defined breakpoints. Format show break Example zsim{32} show break 8.2.36 show dcache This command displays the current contents of the data cache. Format show dcache Example 8-26 ZSIM Simulator For zsim400 simulator R13 R13 R13 R14 R14 R14 R15 R15 R15 UL UL UL UL UL UL UL UL zsim{1}> show dcache - D$[ 0]: ------ I ------ D$[ 1]: ------ I ------ D$[ 2]: ------ I ------ D$[ 3]: ------ I ------ D$[ 4]: ------ I ------ D$[ 5]: ------ I ------ D$[ 6]: ------ I ------ D$[ 7]: ------ I ------ D$[ 8]: ------ I ------ D$[ 9]: ------ I ------ D$[10]: ------ I ------ D$[11]: ------ I ------ D$[12]: ------ I ------ D$[13]: ------ I ------ D$[14]: ------ I ------ D$[15]: ------ I ------ D$[16]: ------ I --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The first 9 lines are dedicated for linked load of r13, 14, and 15 register respectively. The next 8 lines are used for any unlinked load. The first "------" column is showing the address of the line. The next column indicates the line invalid `I' or valid. The next 4 columns are showing the data contains in that line. For zsimg2 > zsim{1}> show dcache D$[ 0] 0x000001 ----------- ------ lru[0] D$[ 1] 0x000001 ----------- -----D$[ 2] 0x000001 ----------- -----D$[ 3] 0x000001 ----------- -----D$[ 4] 0x000001 ----------- -----D$[ 5] 0x000001 ----------- -----D$[ 6] 0x000001 ----------- -----D$[ 7] 0x000001 ----------- -----D$[ 8] 0x000001 ----------- ------ ------ ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ----------- ------ ------ ------ ------ ZSIM Commands 8-27 D$[ 9] 0x000001 ------ ------ ------ ------ ------ ----------- -----D$[10] 0x000001 ------ ------ ------ ------ ------ ----------- -----D$[11] 0x000001 ------ ------ ------ ------ ------ ----------- -----The first column shows the address and the next 8 columns contain data. 8.2.37 show dmem This command displays a range of internal or external data memory. The user specifies internal or external memory, the starting address, and the size of the region to display. The default settings for the show dmem command are shown in Table 8.9. Table 8.8 Argument {int | ext} addr size Default Arguments for show dmem Value int 0x0 16 Format show dmem {int|ext} addr size Example zsim{32} show dmem int 0xf000 0x10 For zsimg2, user can use a symbol instead of an absolute address. zsim{1} show dmem int array1 20 8.2.38 show icache This command displays the current contents of the instruction cache. Format show icache 8-28 ZSIM Simulator Example zsim{32} show icache 8.2.39 show imem This command displays a range of internal or external instruction memory. The size and addr fields may be omitted, in which case defaults are used. The default settings for the show imem command are shown in Table 8.9. Table 8.9 Argument {int | ext} addr size Default Arguments for show imem Value int 0x0 16 Format show imem {int|ext} [addr] [size] Example zsim{1} show imem int 0xf000 0x10 For zsimg2, user can use symbol instead of absolute address value. zsim{1} show imem int foo_function 20 8.2.40 show pipe This command shows the contents of all stages of the pipeline. Format show pipe Example zsim{32} show pipe ZSIM Commands 8-29 8.2.41 show profile This command shows the current status (enabled/disabled) for each profile type. Format show profile Example zsim{32} show profile ***(info) Supported profile information: - Instruction Unit: OFF - Data Unit: OFF - Pipeline Unit: OFF 8.2.42 show reg This command displays the values of a category of registers or the value of the specified register. You can list more than one category and/or register. The register categories are: * * gpr All general purpose registers, r0-r15. cfg All control registers (such as %smode and %hwflag). Do not include the percent (%) sign in the control register name. * addr All address and index registers for the ZSPG2 architecture. Thus, it is specific for zsimg2. Format show reg [category|register] ... Examples zsim{32} show reg zsim{32} show reg r0 zsim{32} show reg hwflag smode (Do not include the percent (%) sign.) 8-30 ZSIM Simulator 8.2.43 show rule This command displays the affected grouping rule for the current cycle. Format show rule Examples zsim{32} show pipe CYCLE: 8 ------------------------------------------ F(4:2) (13)000d:5448:0:mac2.a r4.e, r8.e (12)000c:788f:0:lddu r8.e, r15, 2 (11)000b:784e:1:lddu r4.e, r14, 2 (10)000a:9a00:1:xor.e r0.e, r0.e ------------------------------------------ G(4:2) (9)0009:2d18:0:movl r13, 0x18 (8)0008:3f00:0:movh r15, 0x0 (7)0007:3d01:1:movh r13, 0x1 (6)0006:3e00:1:movh r14, 0x0 ------------------------------------------ R(0:0) ------------------------------------------ E(1:1) (5)0005:ad02:1:bits fmode, 2 ------------------------------------------ W(1:1) (4)0004:d700:1:movl guard, 0x0 zsim{33} show rule Active grouping rule in current cycle: 23. Only two instructions requiring an alu or one instruction that requires both the alus can be grouped. 8.2.44 show size Show size of internal data or instruction memory. The output is not affected by the radix attribute. Format show size {dmem|imem}{int|ext} Examples zsim{32} The size zsim{32} The size show size dmem int of internal data memory is 0xf800 words. show size imem int of internal instruction memory is 0xf800 words. ZSIM Commands 8-31 8.2.45 show stats Display all the run-time statistics generated by ZSIM. If no argument is specified, ZISIM displays overall statistical information. If the opcode argument is specified, ZISIM displays instruction opcode statistics. Format show stats Example zsim{32} show stats zsim{32} show stats opcode 8.2.46 show trace Show currently enabled/disabled trace information. Traces currently set to ON are enabled during simulation. Format show trace Example zsim{32} show trace ***(info) Supported trace information: - Instruction trace: OFF - Pipeline trace: OFF - Register trace: OFF - Memory trace: OFF zsim{33} enable trace pipe ***(info) Pipeline trace is ON. zsim{34} show trace ***(info) Supported trace information: - Instruction trace: OFF - Pipeline trace: ON - Register trace: OFF - Memory trace: OFF 8.2.47 step Single-step the simulator. Issuing the step command is equivalent to issuing the command run 1. 8-32 ZSIM Simulator Format step Example zsim{32} step 8.2.48 unalias Deletes an alias. Format unalias [alias] Example zsim{32} unalias adv 8.3 I/O Port Usage ZSIM400 models serial I/O as a memory-mapped device. Programs perform terminal I/O by reading from and writing to the appropriate address locations. The simulator defines two serial ports and one host processor interface (HPI) port. Each port has a transmit buffer and a receive buffer. Table 8.10 shows the memory addresses and corresponding files for the I/O ports for the LSI402ZX, LSI403Z, and ZSP400-core based devices. Table 8.10 I/O Device Memory Map and Associated Files Read I/O Port Serial Port 0 Serial Port 1 Host Interface Port Address 0xF901 0xFA01 0xFB01 File sp0in sp1in hpiin Address 0xF900 0xFA00 0xFB00 Write File sp0out sp1out hpiout I/O Port Usage 8-33 The format of input and output files are the same. Data must be in decimal digits, with each data on a single line. If the input file is not present in the current running directory at the time of the request, the simulator will print an error message to standard output and exit. ZSIM400 also supports user-specified I/O ports. You can create a library containing peripheral devices and then use it in place of the default library in the directory $SDSP_HOME/sdspI/bin, which is created when the ZSP SDK tools are installed. The peripheral library is called libzperiph.dll on Windows and libzperiph.so on Solaris platforms. For information on writing the peripheral library, refer to the ZSIM Peripheral API Reference Guide, document DB06-000299-00. 8.4 Example Session Using ZSIM This section contains an example simulation session using ZSIM in interactive mode. zsim{1}> load exe test.exe ***(info) Starting address: 0x2000 .text : Loading to INT-INST memory ... 0x2000 -> 0x2950 (0x0951) .data : Loading to INT-DATA memory ... 0x0001 -> 0x005f (0x005f) Loading "test.exe" successfully. The contents of the instruction memory can be checked to confirm proper loading of the test: zsim{2}> 0x2000 0x2001 0x2002 0x2003 zsim{3}> show imem int 0x2000 4 0x2cfb movl r12, 0xfb 0x3cf7 movh r12, 0xf7 0xa6d0 mov r13, 0x0 0x2460 movl r4, 0x60 _ Before execution cycles begin, you can check to make sure that the pipeline and caches are empty: zsim{3}> show pipe -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------F(0:0) G(0:0) R(0:0) E(0:0) W(0:0) As shown above, the five stages of the execution pipeline are identified with a single letter - F (Fetch/decode), G (Group), R (Read), E (Execute), 8-34 ZSIM Simulator and W (Write Back) - followed by two integers representing the number of instructions currently in that stage and the number of instructions that will advance to the next stage in the following cycle. zsim{4}> show I$[0]: -----I$[1]: -----I$[2]: -----I$[3]: -----I$[4]: -----I$[5]: -----I$[6]: -----I$[7]: -----icache I -----I -----I -----I -----I -----I -----I -----I -----I I I I I I I I ----------------------------------------I I I I I I I I ----------------------------------------I I I I I I I I ----------------------------------------- In the above example, the 8 lines of the instruction cache are shown to be empty . The first column contains the address (4 word boundary) and the remaining 4 columns contain the corresponding instruction opcodes. An `I' to the left of a cell indicates an invalid instruction. zsim{5}> show R13 - D$[ 0]: R13 - D$[ 1]: R13 - D$[ 2]: R14 - D$[ 3]: R14 - D$[ 4]: R14 - D$[ 5]: R15 - D$[ 6]: R15 - D$[ 7]: R15 - D$[ 8]: UL - D$[ 9]: UL - D$[10]: UL - D$[11]: UL - D$[12]: UL - D$[13]: UL - D$[14]: UL - D$[15]: UL - D$[16]: dcache -------------------------------------------------------------------------------------I I I I I I I I I I I I I I I I I ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The 17 lines of the data cache are shown to be empty in the above example. The first column contains the address (4-word boundary) and the remaining 4 columns contain data values. An `I' to the left of a data line indicates that the corresponding data line is invalid. Continuing with the example, as execution proceeds, the pipeline and instruction cache reflect changes expected by instruction flow: zsim{6}> run 4 ; show pipe CYCLE=000004 PC=0x2000 CYCLE: 4 Example Session Using ZSIM 8-35 ------------------------------------------ F(4:1) (7)2007:6054:0:st r5, r4, 0 (6)2006:a051:0:add r5, 0x1 (5)2005:bc54:0:mov r5, r4 (4)2004:3400:1:movh r4, 0x0 ------------------------------------------ G(4:1) (3)2003:2460:0:movl r4, 0x60 (2)2002:a6d0:0:mov r13, 0x0 (1)2001:3cf7:0:movh r12, 0xf7 (0)2000:2cfb:1:movl r12, 0xfb ------------------------------------------ R(0:0) ------------------------------------------ E(0:0) ------------------------------------------ W(0:0) zsim{7}> show icache I$[0]: 0x2000 V 0x2cfb V 0x3cf7 V 0xa6d0 V 0x2460 I$[1]: 0x2004 V 0x3400 V 0xbc54 V 0xa051 V 0x6054 I$[2]: ------ I ------ I ------ I ------ I -----I$[3]: ------ I ------ I ------ I ------ I -----I$[4]: ------ I ------ I ------ I ------ I -----I$[5]: ------ I ------ I ------ I ------ I -----I$[6]: ------ I ------ I ------ I ------ I -----I$[7]: ------ I ------ I ------ I ------ I -----zsim{8}> _ The simulator output below demonstrates use of the PC breakpoint. A breakpoint is set for address 0x10 and the simulator is advanced. Execution halts when the instruction associated with the breakpoint address reaches the Group stage. The state of the pipeline and operand registers are shown after the breakpoint halt occurs. zsim{8}> set break sym main Breakpoint 1 on PC at address 0x2010 of main zsim{9}> enable trace write ***(info) Instruction trace is ON. zsim{10}> run <6> (0) 0x2000 2cfb movl r12, 0xfb ! r12 = 0x00fb <7> (1) 0x2001 3cf7 movh r12, 0xf7 ! r12 = 0xf7fb <7> (2) 0x2002 a6d0 mov r13, 0x0 ! r13 = 0x0000 <8> (3) 0x2003 2460 movl r4, 0x60 ! r4 = 0x0060 <9> (4) 0x2004 3400 movh r4, 0x0 ! r4 = 0x0060 <10> (5) 0x2005 bc54 mov r5, r4 ! r5 = 0x0060 <11> (6) 0x2006 a051 add r5, 0x1 ! hwflag = 0x0030 <11> (6) 0x2006 a051 add r5, 0x1 ! r5 = 0x0061 <11> (7) 0x2007 6054 st r5, r4, 0 ! INT-DATA[0x0060] = 0x0061 <12> (9) 0x2009 2510 movl r5, 0x10 ! r5 = 0x0010 <13> (8) 0x2008 bb1d mov rpc, r13 ! rpc = 0x0000 <13> (10) 0x200a 3520 movh r5, 0x20 ! r5 = 0x2010 <14> (12) 0x200c a750 call r5 ! rpc = 0x200d (PC BREAKPOINT #1)....................... CYCLE=000020 PC=0x2014 Trace information is displayed in six fields: 8-36 ZSIM Simulator * * * * * * The first field is the cycle count number (enclosed by `< >'). The second field is the instruction sequence number (in parenthesis). The third field is the program counter (PC) of the executed instruction. The fourth field is the instruction opcode. The fifth field is the disassembled instruction, including operands. The sixth field describes the result of the executed instruction. zsim{11}> run 7; show pipe <20> (13) 0x2010 2501 movl r5, 0x1 ! r5 <20> (14) 0x2011 b91d mov r13, rpc ! r13 <21> (15) 0x2012 3500 movh r5, 0x0 ! r5 <21> (16) 0x2013 6fdc stu r13, r12, -1 ! INT-DATA[0xf7fb] <21> (16) 0x2013 6fdc stu r13, r12, -1 ! r12 <22> (17) 0x2014 a0cf add r12, 0xffff ! hwflag <22> (17) 0x2014 a0cf add r12, 0xffff ! r12 <22> (19) 0x2016 1060 call 0x20d6 ! rpc <23> (18) 0x2015 615c st r5, r12, 1 ! INT-DATA[0xf7fa] <25> (20) 0x20d6 a641 mov r4, 0x1 ! r4 <26> (21) 0x20d7 b91d mov r13, rpc ! r13 <26> (22) 0x20d8 6fdc stu r13, r12, -1 ! INT-DATA[0xf7f9] <26> (22) 0x20d8 6fdc stu r13, r12, -1 ! r12 <27> (23) 0x20d9 bc6c mov r6, r12 ! r6 CYCLE=000027 PC=0x20dc CYCLE: 27 ------------------------------------------ F(4:3) (33)20ea:bc34:0:mov r3, r4 (32)20e9:6f7c:1:stu r7, r12, -1 (31)20e8:b910:1:mov r0, rpc (30)20e7:6b2c:1:stdu r2.e, r12, -2 ------------------------------------------ G(4:3) (29)20e6:3d00:0:movh r13, 0x0 (28)20e5:6b0c:1:stdu r0.e, r12, -2 (27)20e4:2d68:1:movl r13, 0x68 (26)20dc:1004:1:call 0x20e4 ------------------------------------------ R(1:1) (25)20db:a063:1:add r6, 0x3 ------------------------------------------ E(2:2) (24)20da:725c:1:ld r5, r12, 2 (23)20d9:bc6c:1:mov r6, r12 ------------------------------------------ W(2:2) (22)20d8:6fdc:1:stu r13, r12, -1 (21)20d7:b91d:1:mov r13, rpc zsim{12}> show reg gpr r0 = 0x0000 r1 = 0x0000 r2 = 0x0000 r3 = 0x0000 r4 = 0x0001 r5 = 0x0001 = = = = = = = = = = = = = = 0x2001 0x200d 0x0001 0x200d 0xf7fa 0x0040 0xf7f9 0x2017 0x0001 0x0001 0x2017 0x2017 0xf7f8 0xf7f8 Example Session Using ZSIM 8-37 r6 r8 r10 r12 r14 zsim{14}> = = = = = 0xf7f8 0x0000 0x0000 0xf7f8 0x0000 r7 r9 r11 r13 r15 = = = = = 0x0000 0x0000 0x0000 0x2017 0x0000 Execution halts when a breakpoint is reached, the maximum cycle count is reached, or a system halt occurs. A system halt refers to the halt mode as defined by the power level (lvl) field in the DSP's %smode control register. A simulation session is terminated with the exit command. zsim{12}> exit ***(info) Exiting ZSIM. %_ 8-38 ZSIM Simulator Chapter 9 Debugger This chapter describes the SDK source and assembly-level Debugger for the ZSP400 and ZSPG2 architectures. The SDK Debugger, SDBUG, is based on the GNU Debugger (GDB) from the Free Software Foundation. GDB is described in Debugging with GDB: The GNU Source Level Debugger, by Richard Stallman, et. al., Free Software Foundation, January 1994. The description of SDBUG in this chapter, for the most part, includes only the differences from GDB. For Windows 95/98/NT platforms, the debugger can be accessed using the ZSP Integrated Development Environment, as described in Chapter 10, "ZSP Integrated Development Environment (ZSP IDE)." This chapter describes the debugger's standard GNU command-line interface, available for all platforms. 9.1 Using SDBUG SDBUG is invoked from the command line as follows: ZSP SDK Software Development Kit 9-1 where debugger name is the name of the desired debugger as listed in Table 9.1. Table 9.1 Debugger Names Debugger Name Use when debugging... sdbug400 zdxbug code written for devices based on the ZSP400 architecture. code originally written for devices based on the ZSP400 architecture, but cross-compiled for the ZSPG2 architecture. code designed for devices based on the ZSPG2 architecture. zdbug The above command both invokes and initializes the debugger. SDBUG-only command-line options are listed in Table 9.2. All other SDBUG options are described in Stallman, et. al. Table 9.2 Option -mempcr=ADDR -no_mempcr -jtag_type=TYPE SDBUG-Only Options Description Availability Sets the address of the mempcr register. sdbug400 Specifies that the hardware target has no MEMPCR register Gives priority to the detection of the JTAG interface specified. TYPE can be either pci (Corelis PCI JTAG), pcmcia (Corelis PCMCIA JTAG), or raven (Macraigor Raven) By default, SDBUG first attempts to use the PCMCIA JTAG card, then the PCI JTAG card, then the Macraigor Raven interface.. sdbug400 sdbug400 -jtag_mapfile=FILE Makes the debugger look for the map file FILE, rather than the default called "mapfile" in the current directory and SDSP_HOME/sdspI/misc. sdbug400 Use the following command to load the symbol table from the executable file: (sdbug) file a.out 9-2 Debugger Next select SDBUG's target execution environment (as described in the following section). For example, to target the cycle-accurate simulator: (sdbug) target zsim Use the following command to load the text and data sections of the executable file: (sdbug) load a.out Now you are ready to debug your program using the standard GDB commands. 9.2 SDBUG Execution Environments The debugger supports four execution environments: * * * * Functional-accurate software simulation on the host (using ZISIM) Cycle-accurate software simulation on the host (using ZSIM) Target hardware, connected through the serial port Target hardware, connected through a JTAG controller (Windows 95/98/NT platforms only) These environments are described in the following subsections. 9.2.1 Functional-Accurate Simulator Connection The ZISIM target simulator is invoked by the following command: (sdbug) target sim [option...] where option is any of the simulator options described in Table 7.1 on page 7-1. With this connection, program execution is performed by the functional-accurate simulator, ZISIM, under the control of the debugger. The debugger examines the simulator state to process queries from the user. SDBUG uses the functional-accurate simulator commands to select information that is requested from the executing program by the ZISIM SDBUG Execution Environments 9-3 simulator. These commands are listed in Table 9.3 and described in detail in Section 7.2, "ZISIM Commands," page 7-4. The format for simulator commands using ZISIM is: (sdbug) sim simulator-command Table 9.3 Command clear-stats close filename help max_number_of_files number SDBUG Target ZISIM Simulator Commands Description Resets the statistics. Closes file filename.1 Displays the list of simulator commands that can be invoked. Sets the maximum number of files that can be opened at the same time to number.1 memory_download filename addr size Writes size of items to memory addr from file filename.1 memory_upload filename addr size print-stats reg-off reg-on trace-off trace-on clear-opcode print-opcode Reads size of items from memory addr to file filename.1 Prints statistics such as instruction mix, load, store, discontinue, and mispredicts to stdout. Sets the simulator register tracing off. Sets the simulator register tracing on. Sets the simulator trace off. Sets the simulator trace on. Resets statistics of opcode usage. Prints statistics of opcode usage. 1. This command may also be invoked without specifying the target name. See Section 9.3.1, "Generic Target-Specific Commands" on page 9-11 for details. 9.2.2 Cycle-Accurate Simulator Connection The ZSIM target simulator is invoked by the following command: (sdbug) target zsim 9-4 Debugger With this connection, the cycle-accurate simulator (ZSIM) executes your program under the control of the debugger. The debugger examines the simulator state to process queries from the user. The cycle-accurate simulator commands are used to select information that is requested from the executing program by the ZSIM simulator. These commands are listed in Table 9.4 and described in detail in Section 8.2, "ZSIM Commands," page 8-5. The format for ZSIM commands is: (sdbug) zsim simulator-command Table 9.4 Command clear-stats clear-opcode close filename help max_number_of_files number memory_download filename addr size memory_upload filename addr size pfdu-off pfdu-on pfiu-off pfiu-on pfpipe-off pfpipe-on pipe-off (Sheet 1 of 2) SDBUG Target ZSIM Commands Description Resets the general statistics. Resets the opcode usage statistics. Closes file filename.1 Displays the list of simulator commands that can be invoked. Sets the maximum number of files that can be opened at the same time to number.1 Writes size of items to memory addr from file filename.1 Reads size of items from memory addr to file filename.1 Turns off data unit profile information. Turns on data unit profile information. Turns off instruction unit profile information. Turns on instruction unit profile information. Turns off pipeline unit profile information. Turns on pipeline unit profile information. Sets the simulator pipeline off. SDBUG Execution Environments 9-5 Table 9.4 Command pipe-on print-dcache print-icache print-opcode print-pipe SDBUG Target ZSIM Commands (Cont.) Description Sets the simulator pipeline on. Prints contents of data cache to stdout. Prints contents of instruction cache to stdout. Prints instruction opcode history to stdout. Prints contents of the pipeline to stdout. Prints collected profile information to stdout. Prints grouping rule to stdout2. When cycle count is on, prints statistics to stdout. Prints incremental statistics information to stdout. Collects profile information for functionName from start to end addresses. Follow by profile-on command to turn on the profile collector. Collects profile information for all functions in the program. Follow by the profile-on command to turn on the profile collector. Turns off profile collector. Turns on profile collector Sets the simulator register tracing off. Sets the simulator register tracing on. Sets the simulator trace off. Sets the simulator trace on. print-profile print-rule [# | all] print-stats print-stats-inc pf functionName start end profile-func profile-off profile-on reg-off reg-on trace-off trace-on (Sheet 2 of 2) 1. This command may also be invoked without the target name. See Section 9.3.1, "Generic TargetSpecific Commands" on page 9-11 for details. 2. The optional arguments only work in sdbug400. zdbug and zdxbug only supports the display of the grouping rules that are currently active. 9.2.2.1 User-Specified Profiling When used with the cycle-accurate simulator, the debugger supports profiling of selected areas of your project code. To use this feature, you 9-6 Debugger must define the regions to be profiled using the following pair of assembler directives in your source code: asm("\n__FUNC_START_region_name:"); asm("\n__FUNC_EXIT_region_name:"); The profiling can then be enabled using the following commands: (sdbug) profile-func (sdbug) profile-on Execute the program by typing: (sdbug) run Display the profiling statistics using: (sdbug) print_profile With respect to profiling, the profile-func command will treat region_name just like a function. Note that for function profiling to operate correctly, execution that passes through the start label must also pass through the exit label. |
Price & Availability of ZSP
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |